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Notices 


References in this publication to IBM products, programs, or services do not imply that IBM intends to 
make these available in all countries in which IBM operates. Any reference to an IBM product, program, 
or service is not intended to state or imply that only that IBM product, program, or service may be used. 
Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent 
product, program, or service may be used instead of the IBM product, program, or service. The evaluation 
and verification of operation in conjunction with other products, except those expressly designated by IBM, 
are the responsibility of the user. 


IBM may have patents or pending patent applications covering subject matter in this document. The fur- 
nishing of this document does not give you any license to these patents. You can send license inquiries, 
in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 
10594, U.S.A. 


Licensees of this program who wish to have information about it for the purpose of enabling: (i) the 
exchange of information between independently created programs and other programs (including this one) 
and (ii) the mutual use of the information which has been exchanged, should contact the software interop- 
erability coordinator. Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 


Address your questions to: 


IBM Corporation 

Software Interoperability Coordinator 
3605 Highway 52 N 

Rochester, MN 55901-7829 USA 


This publication could contain technical inaccuracies or typographical errors. 


This publication may refer to products that are announced but not currently available in your country. This 
publication may also refer to products that have not been announced in your country. IBM makes no 
commitment to make available any unannounced products referred to herein. The final decision to 
announce any product is based on IBM's business and technical judgment. 


This publication contains examples of data and reports used in daily business operations. To illustrate 
them as completely as possible, the examples include the names of individuals, companies, brands, and 
products. All of these names are fictitious and any similarity to the names and addresses used by an 
actual business enterprise is entirely coincidental. 


This publication contains small programs that are furnished by IBM as simple examples to provide an 
illustration. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function of these programs. All programs contained herein 
are provided to you "AS IS". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. 
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Programming Interface Information 


This publication is intended to help application programmers use the SNA Upline Function of the IBM 
OS/400 licensed program. This publication documents General-Use Programming Interface and Associ- 
ated Guidance Information. 


General-Use programming interfaces allow the customer to write programs that obtain the services of 
OS/400 licensed program. 
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About SNA Upline Facility Programming, SC41-5446 


This book provides the programming information 
you need to use Systems Network Architecture 
(SNA) upline facility (SNUF) with the IBM AS/400 
system. This book also discusses the SNA 3270 
program interface for SNUF that allows an AS/400 
application to communicate with a host application 
by sending and receiving 3270 data streams. This 
book should be used with the book, /CF Program- 
ming. You should be familiar with the concepts 
explained in the CF Programming book and apply 
those concepts to the information presented here 
for using SNUF. 


For a list of related publications, see the 
“Bibliography” on page H-1. 


Who Should Use This Book 


This book is intended for application programmers 
for the AS/400 system, application programmers 
for the remote CICS/VS or IMS/VS system, and 
programmers for the remote system. 


You should be able to program in the language 
you intend to use and be familiar with Systems 
Network Architecture (SNA) concepts and termi- 
nology. You should be familiar with the following 
information: 


e The concepts of communications configuration 
described in the Communications Configura- 
tion book. 


e The concepts of intersystem communications 
function (ICF) support described in the /CF 
Programming book. 


¢ Operations and tasks described in System 
Operation book. 


¢ AS/400 system programming (mainly work 
station) terminology. 


e In some cases, terminology of the remote 
system. 
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¢ If you are using SNA 3270 program interface, 
you should be familiar with 3270 device emu- 
lation and data stream concepts. 


e If you are using 3270 binary synchronous 
communications (BSC) device emulation, you 
should refer to the IBM System/38 Data Com- 
munications Programmer's Guide, SC21-7825, 
and the IBM System/38 3270 Emulation Ref- 
erence Manual and User's Guide, SC21-7961. 


Prerequisite and Related 
Information 


For information about other AS/400 publications 
(except Advanced 36), see either of the following: 


e¢ The Publications Reference book, SC41-5003, 
in the AS/400 Softcopy Library. 

¢ The AS/400 Information Directory, a unique, 
multimedia interface to a searchable database 
that contains descriptions of titles available 
from IBM or from selected other publishers. 
The AS/400 Information Directory is shipped 
with the OS/400 operating system at no 
charge. 


Information Available on the 
World Wide Web 


More AS/400 information is available on the World 
Wide Web. You can access this information from 
the AS/400 home page, which is at the following 
uniform resource locator (URL) address: 


http: //www.as400.ibm.com 


Select the Information Desk, and you will be able 
to access a variety of AS/400 information topics 
from that page. 
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Chapter 1. Introduction to SNA Upline Facility (SNUF) 


The SNA upline facility (SNUF) provides distrib- 
uted data processing to AS/400* users who want 
to communicate with a remote host system 
through Systems Network Architecture (SNA). 
The host system can be a System/370* computer, 
System/390* computer, 30xx, or 43xx processor 
using either Customer Information Conirol 
System for Virtual Storage (CICS/VS) or Infor- 
mation Management System for Virtual Storage 
(IMS/VS). CICS/VS is a licensed program that 
operates on a host system, such as the 
System/370, which can be used in a communica- 
tions network. IMS/VS is a general purpose 
system that enhances the capabilities of OS/VS 
for batch processing and telecommunication. It 
allows users to access a computer-maintained 
database through remote terminals. 


SNUF handles the communications support 
needed to connect the AS/400 system to a host 
system. It allows you to write programs that can 
communicate with either CICS/VS or IMS/VS ona 
specific host system, without being concerned with 
the unique communications requirements of the 
host system. SNUF provides both an interactive 
and a batch communications interface between 
the AS/400 system and the host system. 


SNUF Capabilities 


SNUF has the following capabilities: 


¢ AS/400 programs can start system tasks or 
user programs on host systems with CICS/VS 
or IMS/VS. 


¢ CICS/VS and IMS/VS tasks on a host system 
can start programs on the AS/400 system. 


¢ More than one program on an AS/400 system 
can communicate at the same time with 
CICS/VS or IMS/VS programs on a host 
system. 


e SNUF can share a communications line with 
other SNA-based functions on the AS/400 
system. See the Communications Configura- 
tion book for a description of the total number 
of lines available on the AS/400 system and 
for a list of the SNA-based functions available. 
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¢ Remote locations are defined for SNUF net- 
works as part of the AS/400 configuration 
process. 


e SNUF can run a single session per device. 
There can be more than one device per con- 
troller. A maximum of 255 SNUF devices can 
be attached to the same controller. 


e¢ Data lengths to be sent and received by your 
AS/400 system SNUF application program can 
be defined to a maximum of 32,767 charac- 
ters. 


e SNUF application programs can be written 
using any of the high-level languages (HLLs), 
Integrated Language Environment (ILE) 
C/400*, ILE COBOL/400*, ILE 
FORTRAN/400*, or ILE RPG/400* program- 
ming languages, together with the AS/400 
data description specifications (DDS) 
keywords or the system-supplied formats. 


e¢ The SNUF 3270 support allows the AS/400 
system to communicate with a System/370, 
System/390, 30xx, or 43xx host application by 
sending and receiving 3270 data streams. 


¢ Communications between an AS/400 program 
and a host system program occurs in either 
half-duplex flip-flop or half-duplex contention 
modes. 


e¢ SNUF allows retail pass-through support when 
a host system is connected to the AS/400 
system and the AS/400 system is connected 
to various retail controllers. (Retail commu- 
nications supports the session between the 
retail controller and the AS/400 system. 
SNUF communications supports the session 
between the AS/400 system and the remote 
host system.) See the Retail Communications 
Programming book. 


Communications Line Support 
SNUF uses the following communications lines: 
e Synchronous data link control (SDLC) lines 


— Point-to-point switched (manual answer, 
automatic answer, manual call, or auto- 
matic call) 


— Point-to-point nonswitched 
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— Multipoint nonswitched AS/400 system physically residing on an 
° X25 lines Ethernet LAN if the two LANs are connected 


* Token-ring lines with an 8209 LAN bridge. 


e Ethernet lines 


e Integrated services digital network (ISDN) data 


link control (IDLC) lines SNUF Communications Network 
Note: When the host system physically Figure 1-1 illustrates a SNUF network that com- 
resides on a token-ring local area network municates with several remote systems using dif- 
(LAN) it may communicate, using SNUF, to an ferent communications lines. 
AS/400 System 
Your Program 
Host 
System 
Multipoint Nonswitched 


ICF Data Management 


Secondary Secondary 


fl 
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)\ 
~~ 


SNUF (These can communicate with the remote 
host system, but not with the AS/400 system.) 
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Figure 1-1. SNUF Communications Network 
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Chapter 2. Configuring SNUF Communications 


This chapter discusses how to set up SNA upline 
facility (SNUF) by creating line, controller, and 
device descriptions. 


Creating SNUF Descriptions 


Before you can use SNUF for communications, 
you must create configuration descriptions for 
lines, controllers, and devices that will be used 
with SNUF. 


AS/400 system support allows you to create more 
than one configuration description on the system. 
You use commands to configure SNUF support in 
two ways: 


e Using the command prompt. Enter the 
command and press F4 (Prompt). A prompt 
menu appears for the command. Answer the 
prompts as described in the Communications 
Configuration book. 


e Using direct entry. Enter the command and 
its parameters using the syntax described in 
the CL Reference book. 


The following briefly introduces the commands you 
use to configure SNUF. Create these descriptions 
in the order presented. For a complete 
description of these and related commands, see 
the Communications Configuration book. 


Creating a Line Description 


The line description defines the communications 
line used to communicate with the remote system. 
Valid line types for SNUF communications are 
synchronous data link control (SDLC), X.25, 
token-ring network, Ethernet, and integrated ser- 
vices digital network (ISDN) data link control 
(IDLC). 


The following commands allow you to create a line 
description for use with SNUF: 


¢ Create Line Description (SDLC) 
(CRTLINSDLC) 

¢ Create Line Description (X.25) (CRTLINX25) 

¢ Create Line Description (Token-Ring) 
(CRTLINTRN) 
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¢ Create Line Description (Ethernet) 
(CRTLINETH) 
¢ Create Line Description (IDLC) (CRTLINIDLC) 


If you are using an integrated services digital 
network (ISDN), a connection list and network 
interface description also need to be created 
and defined. The book, [SDN Support con- 
tains more information about configuring an 
ISDN network. 


Creating a Controller Description 


Create a controller description after you have 
created a line description. The controller 
description defines the characteristics of the 
remote system. 


Use the Create Controller Description (SNA Host) 
(CRTCTLHOST) command to configure a con- 
troller for use with SNUF. 


Creating a Device Description 


Create a device description after you have created 
a controller description. The device description 
defines the characteristics of the device your 
application program is going to communicate with. 


Use the Create Device Description (SNUF) 
(CRTDEVSNUF) command to create a device for 
a SNUF application. 


Changing or Deleting a SNUF 
Description 


Use the following commands to change a SNUF 
description: 


¢ Change Line Description (SDLC) 
(CHGLINSDLC) 

¢ Change Line Description (X.25) (CHGLINX25) 

¢ Change Line Description (Token-Ring) 
(CHGLINTRN) 

¢ Change Line Description (Ethernet) 
(CHGLINETH) 

¢ Change Line Description (IDLC) 
(CHGLINIDLC) 

¢ Change Controller Description (SNA Host) 
(CHGCTLHOST) 
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¢ Change Device Description (SNUF) 
(CHGDEVSNUF) 


Use the following commands to delete a SNUF 
description: 


¢ Delete Line Description (DLTLIND) 
¢ Delete Controller Description (DLTCTLD) 
¢ Delete Device Description (DLTDEVD) 
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Displaying a SNUF Description 


Use the following commands to display a SNUF 
description: 


¢ Display Line Description (DSPLIND) 
¢ Display Controller Description (DSPCTLD) 
¢ Display Device Description (DSPDEVD) 


Chapter 3. Running SNUF Communications 


This chapter contains the information you need to 
run your network, including information on the 
Vary Configuration (VRYCFG) command. See the 
book, Communications Management for additional 
information on running communications support. 


The Vary Configuration (VRYCFG) command is 
used to start and end communications support. 


The VRYCFG command with STATUS(*ON) spec- 
ified starts or activates the link between two or 
more systems, and associates the communica- 
tions support with a particular configuration con- 
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sisting of line, controller, and device descriptions 
(if manually created). 


The VRYCFG command with STATUS(*OFF) 
specified ends the link between two or more 
systems and releases the communications 
support. No further communication is possible 
between the systems until the specified configura- 
tions are varied on again. 


For additional information on the Vary Configura- 


tion command, see the book, Communications 
Management. 
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Chapter 4. Writing SNUF Application Programs 


This chapter describes how an application 
program uses the intersystem communications 
function (ICF) file and SNA upline facility (SNUF) 
communications support. The program can be 
coded using high-level languages (HLLs) that 
support an interface that allows the program to do 
the following functions: 


e Start a session by opening an ICF file and 
acquiring a program device. 

¢ Send and/or receive information by writing or 
reading to an ICF file. 

e End a session by releasing the program 
device and closing the ICF file. 


The chapter also includes a description of the 
read and write operations that specify a record 
format containing specific communications func- 
tions. Record formats can be defined using data 
description specifications (DDS) or you may use 
system-supplied formats. 


After an operation completes, a return code (and a 
HLL file status) is returned to your application. 

The return code indicates whether the operation 
completed successfully or unsuccessfully. Along 
with the return code, exception messages may 
also be issued. See Appendix B for more infor- 
mation about return codes and the appropriate 
language reference books for more information 
about the HLL file status. 


Note: Before running application programs on 
your system, you must define the application envi- 
ronment. See the following publications for addi- 
tional information: 


¢ Communications Configuration 
¢ Communications Management 
¢ ICF Programming 

¢ Work Management 


Intersystem Communications 
Function (ICF) File 


An intersystem communications function (ICF) 
file handles all communications between your 
program and the program on the remote system. 
The ICF file must be created before your applica- 
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tion can use SNUF. For more information about 
the ICF file, see the book, ICF Programming. 


The ICF file is a system object of type *FILE with 
a specific user interface. This interface is made 
up of a set of commands and operations. The 
commands allow you to manage the attributes of 
the file and the operations allow a program to use 
the file. Commands allow you to create, delete, 
change, and display the file description. 


The following commands are valid for the ICF file. 


CRTICFF Create ICF file and file-level 
attributes. This command 


allows you to create an ICF file. 


Change ICF file. This 
command allows you to change 
the file attributes of the ICF file. 


Override ICF file. This 
command allows you to tempo- 
rarily change the file attributes 
of the ICF file at run time. 
These changes are only in 
effect for the duration of the job 
and do not affect other users of 
the file. 


CHGICFF 


OVRICFF 


DLTF Delete file. This command 
allows you to delete a file from 


the system. 


DSPFD Display file description. This 
command displays the file 
description of any file on the 
system. The information may 


be printed or displayed. 


DSPFFD Display field description. This 
command displays the 

description of the fields in any 
file on the system. This infor- 
mation may be printed or dis- 


played. 


Add ICF device entry. This 
command allows you to perma- 
nently add a program device 
entry that contains a program 
device name, remote location 
information, and session-level 
attributes. 


ADDICFDEVE 
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CHGICFDEVE Change ICF device entry. This 
command allows you to perma- 
nently change the program 
device attributes previously 
added with the ADDICFDEVE 


command. 


OVRICFDEVE Override ICF device entry. 


This command allows you to: 


¢ Temporarily add the 
program device entry, the 
remote location information, 
and the session-level attri- 
butes to the ICF file. 

¢ Override a program device 
entry with the specified 
remote location information 
and session-level attributes 
for an ICF file. 


Remove ICF device entry. This 
command allows you to perma- 
nently remove the program 
device entry previously added 
with the ADDICFDEVE 
command or changed with the 
CHGICFDEVE command. 


RMVICFDEVE 


The commands CRTICFF, CHGICFF, and 
OVRICFF have a WAITFILE parameter. Use this 
parameter to specify the number of seconds that 
the program waits for the file resources to be allo- 
cated when the file is opened and a device is 
acquired. You must specify the number of 
seconds that the program waits for the file 
resources to be allocated. A value of 1 through 
32 767 can be specified. 


The commands ADDICFDEVE, CHGICFDEVE, 
and OVRICFDEVE have specific parameters that 
are needed for SNUF communications. 

Figure 4-1 describes the SNUF parameters for the 
ADDICFDEVE, CHGICFDEVE, and OVRICFDEVE 
commands. 


For a complete description of all the parameters 
for these commands, see the book, ICF Program- 
ming. See the CL Reference book for the syntax 
of the commands. 
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Figure 4-1. Command Parameters 


ADDICFDEVE, 
Description OVRICFDEVE, 
or 
CHGICFDEVE 
Command 
Parameter 
File name (ADDICFDEVE and FILE 
CHGICFDEVE only) 
Program device name PGMDEV 
Remote location name RMTLOCNAME 
Communications type CMNTYPE 
Device description name DEV 
Input record selection method FMTSLT 
Host application identifier APPID 
Batch or interactive session flag BATCH 
Host subsystem type HOST 
End session with host ENDSSNHOST 
Input function management header HDRPROC 
handling method 
Special host application SPCHOSTAPP 
Initialize self-selection INZSELF 
Message protection flag MSGPTC 
Emulated device EMLDEV 
Maximum record length RCDLEN 
Maximum block length BLKLEN 
Override protection flag SECURE 


(OVRICFDEVE only) 


The following parameters have a special meaning 


for SNUF communications: 


FILE 


Specifies the name and library of the ICF file 
to which you are adding the program device 
entry. The FILE parameter is available only 
with the ADDICFDEVE and CHGICFDEVE 


commands. 


filename: A 1- to 10-character value that 


specifies the name of the ICF file. 


*LIBL: SNUF communications support uses 
the library list to locate the ICF file. This is 


the default value. 


*CURLIB: SNUF communications support 
uses the current library for the job to locate 


the ICF file. If no current library entry exists in 
the library list, SNUF uses QGPL. 


library-name: A 1- to 10-character value that 
specifies the library where the ICF file is 
located. 


PGMDEV 


Specifies the program device name that is 
defined in the ICF file and specified in the 
application. The total number of devices that 
can be acquired to an ICF file is determined 
by the MAXPGMDEV parameter on the 
CRTICFF or CHGICFF command. 


pgm-device-name: Type the name by which 
the user program will refer to this communica- 
tions session. 


RMTLOCNAME 


Specifies the remote location name with which 
your program communicates. A remote 
location name must be specified on the 
ADDICFDEVE command or an OVRICFDEVE 
command. If a remote location name is not 
specified, return code 82EE is returned to 
your program when the program device is 
acquired. 


*REQUESTER: The name used to refer to 
the communications device through which the 
program was started. 


remote-location-name: Type a 1- to 
8-character name for the remote location 
name that should be associated with the 
program device. 


Note: For additional information on how the 
remote location name is used for device 
selection, see the discussion of the DEV 
parameter later in this section. 


CMNTYPE 


Identifies the communications type for which 
you define a program device entry. You 
should specify the value *SNUF or *ALL for 
this parameter. 


*ALL: This default value specifies that all 
parameters appear in the prompt. 


*SNUF: The prompt for all SNUF supported 
parameters. 


Note: When you specify “REQUESTER for 
the remote location name (RMTLOCNAME), 
you are prompted for the attributes of the 
emulated device (EMLDEV), format select 
(FMTSLT), record length (RCDLEN), block 
length (BLKLEN), and secure (SECURE) 
parameters. 


DEV 


Specifies the communications device used in 
the remote location. This parameter must be 
specified for SNUF support. 


*LOC: The device will be determined by the 
system. 


When *LOC is specified for the DEV param- 
eter and the value for the RMTLOCNAME 
parameter is not *REQUESTER, then the 
device chosen is determined by the system 
according to the device selection criteria of 
SNUF. 


SNUF acquires the first device with the speci- 
fied remote location name that is varied on 
and not in use. 


If no varied-on device is available, SNUF 
attempts to acquire a device in the vary-on 
pending state. If such a device is not avail- 
able, SNUF chooses a device with a less 
favorable priority. 


SNUF device selection is made, in the fol- 
lowing priority, from devices with the specified 
remote location name that are not in use and 
are otherwise serviceable: 


. Varied on 

. Vary-on pending 

. In queried, suspend, or reset states 

. Recovery pending or inoperative pending 
state 

5. Held immediate state 

6. Held controlled state 


OND — 


device-name: Type the 1- to 10-character 
name of the device that is associated with the 
remote location. 


FMTSLT 


Specifies the type of record format selection 
used for input operations for all devices. 


*PGM: The program determines what record 
formats are selected. This is the default 
value. 


*RECID: The RECID keywords specified in 
DDS for the file are used to specify record 
selection. 


APPID 


This parameter specifies the VTAM* identifier 
of the CICS/VS or IMS/VS host system. 
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*DEVD: Specifies that the application identi- 
fier specified in the device description is sent 
with the logon message. This is the default 
value. 


*USER: Specifies that the application 
program receives the USSMSG message and 
sends a logon command to the host system. 
This is valid only when using the 3270 
program interface. 


application-ID: The specified application iden- 
tifier is sent with the logon message. 


BATCH 


Specifies if batch processing is performed for 
the session with the CICS/VS or IMS/VS host 
system. See “Sending Records in Chains” on 
page 5-2 for a complete discussion of batch 
and interactive sessions. 


*NO: Specifies that the session will be 
running in interactive mode. This is the 
default value. 


*YES: Specifies that the session will be 
running in batch mode. 


Note: If you specify 
RMTLOCNAME(*REQUESTER), this param- 
eter is ignored. The program started by the 
remote system is always running in batch 
mode. 


HOST 


This parameter specifies the remote or host 
system with which this session is communi- 
cating. 


*DEVD: The host system specified in the 
device description is used. This is the default 
value. 


*CICS: The session communicates with 
CICS/VS. 


*IMS: The session communicates with 
IMS/VS. 


*IMSRTR: The session communicates with 
IMS/VS using the ready-to-receive option. 


ENDSSNHOST 


This parameter specifies the end of a session 
with the host system. 


*RSHUTD: Specifies the Request Shut Down 
command to the host system. Most host 
applications recognize this command. This is 
the default value. 
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*TERMSELF: This value may be set to issue 
a TERM-SELF command to the host system. 
This value is used when the host application 

does not recognize the default value. 


SPCHOSTAPP 


Specifies whether SNUF should customize 
support for special host applications outside 
the CICS or IMS application layer. 


*DEVD: The value specified in the device 
description is used. This is the default value. 


*NONE: No customization for the special host 
application is needed. 


*FLASH: Customization for the Federal 
Reserve communication application, Federal 
Link Access for Secondary Half-sessions 
(FLASH), is required. 


INZSELF 


Specifies whether a formatted INIT-SELF is 
sent to the host system in place of an unfor- 
matted logon. 


*NO: Use the unformatted logon provided by 
SNUF. This is the default value. 


*YES: Use the formatted INIT-SELF provided 
by SNUF. 


HDRPROC 


This parameter specifies, for both CICS/VS 
and IMS/VS, if function management headers 
are passed to the application program. 


*SYS: SNUF removes function management 
headers before passing data to the program. 
This is the default value. 


*USER: Function management headers are 
passed to the program. 


MSGPTC 


This parameter specifies for both CICS/VS 
and IMS/VS whether message protection is 
used for this session. 


*YES: Message protection is used. SNUF 
saves messages until they are responded to, 
and uses these messages to determine if data 
must be sent again when a line, controller, or 
device failure occurs. This is the default 
value. 


Transmission services profile 03 is not sup- 
ported if message protection is requested. 


Note: *YES is only valid when processing is 
not running in batch (BATCH(*NO) is speci- 
fied). 


*NO: Message protection is not used. 


EMLDEV 
This parameter specifies whether or not the 
application is sending and receiving 3270 data 
streams. 


*NONE: This default value specifies that the 
program device entry is not used to send and 
receive 3270 data streams. 


32xx: One of these values specifies that the 
device is used to send and receive 3270 data 
streams. 


Note: If a value other than (*NONE) is speci- 
fied, you are specifying that this device will 
send and receive 3270 data streams. 


See “ICF File Considerations” on page D-1 for 
a complete description of this parameter and 
the SNA 3270 program interface for SNUF. 


RCDLEN 
This parameter specifies the maximum record 
length (in bytes) for the logical record of data 
being sent and received from your program. 
The specified length should not exceed the 
length of the input/output buffer, which is 
determined by the value of the MAXRCDLEN 
parameter on the CRTICFF command. 


*DEVD: The record length specified in the 
device description is used. This is the default 
value. 


record-length: Type the maximum record 
length when using this device file. The value 
must be at least the size of the largest record 
sent and cannot exceed 32 767 bytes. 


For SNA 3270 program interface, ensure that 
the specified length accommodates the larger 
32 byte header, the largest display image pos- 
sible with your application program, and pos- 
sible field definitions that may follow the 
display or printer image. 


Note: If a record is longer than the specified 
maximum record length, a run-time error 
occurs at the time the record is sent or 
received. 


BLKLEN 
This parameter specifies the maximum block 
length (in bytes) for data sent. 


*DEVD: The block length specified in the 
device description is used. This is the default 
value. 


block-length: Specify the maximum block 
length of records sent or received when using 
this device file. The value must be greater 
than or equal to the value of RCDLEN, but 
cannot exceed 32 767 bytes. 


SECURE 
This parameter is valid only on the 
OVRICFDEVE command and does not apply 
to either the ADDICFDEVE or the 
CHGICFDEVE commands. It is used to 
restrict the effects of override processing. 


*NO: Specifies no protection from other 
program device overrides. 


*YES: Specifies this program device is 
secure from previously called override com- 
mands. 


Comparing Configuration and 
Program Device Entry Command 
Parameters 


The parameter values from the configuration com- 
mands are used for any SNUF session, unless 
those values are changed by the program device 
entry commands. 


Figure 4-2 on page 4-6 shows the relationship 
between the SNUF parameters for the program 
device entry commands (ADDICFDEVE, 
CHGICFDEVE, and OVRICFDEVE) and the con- 
figuration commands. If there is no configuration 
parameter corresponding to the program device 
entry parameter, it is marked with a dash (-). 
Except where noted, you specify all configuration 
parameters when you create the device 
description (CRTDEVSNUF command). 


The ADDICFDEVE and CHGICFDEVE program 
device entry commands cause permanent 
changes for any SNUF session using the specified 
program device. The OVRICFDEVE program 
device entry command causes job-level changes 
(as long as the OVRICFDEVE command remains 
in effect) for any SNUF session using the speci- 
fied program device. 
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Figure 4-2. Comparing Configuration Command 
Parameters and Program Device Entry Command 
Parameters 


Figure 4-2. Comparing Configuration Command 
Parameters and Program Device Entry Command 
Parameters 


Configuration Program Device 


Configuration Program Device 


Parameter Command Entry Command Parameter Command Entry Command 
Description Parameter Parameter Description Parameter Parameter 

File - FILE1 Authority AUT - 

Program device = PGMDEV Notes: 

nei 1 This parameter is valid only on the ADDICFDEVE and 
Device description DEVD - CHGICFDEVE commands. 

Local location LOCADR - 2 This parameter is valid only on the OVRICFDEVE 

name command. 

Remote location RMTLOCNAME RMTLOCNAME4,5 3 Specify (*DEVD) and the value is retrieved from the device 
name description at run time. This is the default for the param- 

. eter. Specify (*USER) and the application program sends a 
Online at IPL ONEINE _ logon message to the host system. The application 
Communications = CMNTYPE program is also responsible for receiving and handling 
type system services control point-logical unit (SSCP-LU) mes- 
Attached controller CTL - Sages fromthe Host Syston: 

Davies = DEV4 4 These parameters are used by the program device entry to 
associate a program device name with the device 

Format select = FMTSLT description you want to use. See the ICF Programming for 

Program start PGMSTRROQS = more information on defining program device entries. 

request capable 5 If you specify RMTLOCNAME(*REQUESTER) on the 

Apsieaiion’ 7 APPID APPID3 command, you are NOT prompted for these parameters: 

aoe pan dens DEV, APPID, BATCH, HOST, HDRPROC, and MSGPTC. 
The program started by the host request will have acquired 

Batch activity = BATCH the device, so device selection using the RMTLOCNAME 

Host type HOST HOST3 and DEV parameters does not occur. The value 

: (*REQUESTER) is only valid on the ADDICFDEVE, 

End session with - ENDSSNHOST CHGICFDEVE, and OVRICFDEVE commands. 

host system 

Special host appli- - SPCHOSTAPP 

cation 

Initialize self z INZSELF Communications Operations 

Header processing - HDRPROC i 

Mascagni: = MSGPTC This section gives a description of the operations 

tection you can code into a program using SNUF support 

Emilationidavles a EMLDEV to communicate with a host program. 

Device type = device type 


Data format - data format 


Record length RCDLEN RCDLEN3 
Block length BLKLEN BLKLEN3 
Secure from over- - SECURE2 
ride 
Default program DFTPGM - 

library LIBRARY - 
Text description TEXT - 
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For additional information on these operations and 
functions, see the book, [CF Programming. For 
coding examples, see the DDS Reference book. 


Starting a Session 


There are two ways to start a SNUF session: 


e¢ The AS/400 program can issue an 
open/acquire operation to establish a session 
between your program and a program at a 
remote location. See “Open or Acquire 
Operation” on page 4-7. 


¢ The CICS/VS or IMS/VS program can send a 
program start request to the AS/400 system. 
See “Program Start Requests” on page 5-5. 


Open or Acquire Operation 


Your program uses the open or acquire operation 
to establish a session between your program and 
the host system. 


You can start a session implicitly with the open 
operation when you specify the ACQPGMDEV 
parameter on the CRTICFF command, or you can 
start the session explicitly by using the acquire 
operation. 


The open/acquire operation starts the following 
sequence: 


e SNUF sends a sign-on to the host system 
using the application ID (APPID) parameter 
specified when you configured the program 
device entry (ADDICFDEVE) or changed the 
program device entry (OVRICFDEVE or 
CHGICFDEVE). 


e SNUF examines the BIND command parame- 
ters from the host system. 


e SNUF sends your program a normal return 
code when the host system is ready to begin 
the session. 


For a switched connection, the open/acquire oper- 
ation starts a similar sequence. Additional steps 
occur based on how the connection is configured. 
For more information, see the Communications 
Configuration book. 


Sessions started by the acquire operation are 
started with the parameters specified in the 
ADDICFDEVE or OVRICFDEVE command. A 
parameter specified in the OVRICFDEVE 
command overrides any corresponding parameter 
specified in the ADDICFDEVE or CHGICFDEVE 
command. 


Starting a Transaction 


A transaction is a logical connection between two 
programs. Use the evoke function to start a trans- 
action between your system and the host system. 
(A program start request from the remote host 
system is used to start a transaction between the 
host program and your program.) 


Evoke Function 


The evoke function starts a transaction and identi- 
fies the program on the CICS/VS or IMS/VS 
system that is to receive the data. You must 
acquire a program device to establish a session 
before you can issue an evoke function in your 
program. You can issue more than one evoke 
function in a SNUF session to send or receive 
multiple transactions to one or more remote pro- 
grams. However, you cannot issue another evoke 
function in your program until the current trans- 
action is ended by either issuing a detach function 
or receiving a detach indication. The evoke func- 
tion is only supported when in half-duplex flip-flop 
mode. 


The evoke function uses an evoke parameter list 
that identifies the remote program and, if security 
is being used by IMS/VS, the correct password. 
(For CICS/VS, security is handled with a special 
sign-on transaction.) This list can optionally 
contain user-supplied data for the remote 
program. If you use either the EVOKE DDS 
keyword or the system-supplied format (S$EVOk), 
possible parameters are: 


e Remote program name 

e User ID 

e Library name 

e User password 

e User data or program parameters 


Notes: 


1. SNUF ignores the user ID, library name, 
and user password when communicating 
with CICS/VS, and ignores the user ID 
and library name when communicating 
with IMS/VS. 


2. The optional data you can specify with 
each type of evoke function can be user 
data or program parameters. 


When your program issues an evoke function, 
SNUF builds and sends a program start request to 
the host system. The host system receives this 
transaction start record (host terminology), which 
specifies an evoke parameter list containing the 
remote program name (as a transaction code), 
any password you specify, and any additional data 
you supplied. When the remote program starts, 
the host system passes the data you supplied to 
its program. 
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When CICS/VS receives the evoke request, it 
starts the program. When IMS/VS receives the 
evoke request, it schedules the specified program 
for running. IMS/VS specifies the transaction data 
when the program starts. 


Sending Data 


You can send data during a transaction using the 
write operation. Function management headers 
can also be sent with the write operation. 


Write Operation 


The write operation passes data records from your 
program to the remote program. Each write oper- 
ation sends only one record from the SNUF appli- 
cation. To issue a write operation without sending 
data, specify a zero-length output record. (The 
zero-length output record tells SNUF there is no 
data associated with the write operation.) You 
can also use a write operation to send control 
information or commands (such as the IMS/SET 
command) to the host system. You can issue a 
write operation any time you have control of the 
session. 


You can start a transaction with either a write 
operation or evoke function. If you start a trans- 
action with a write operation, you are responsible 
for setting up the data to be sent. 


The manner in which SNUF sends logical records 
depends on the BATCH parameter on the 
ADDICFDEVE or OVRICFDEVE command. If you 
specify BATCH(*NO), SNUF sends each logical 
record as a complete chain. SNUF automatically 
divides records greater than the size of the 
maximum request/response unit (RU) into ele- 
ments of a chain. If you specify BATCH(*YES), 
SNUF divides logical records as required but does 
not chain them. 


Variable length records can be sent by specifying 
the DDS keyword VARLEN for the record con- 
taining the variable length data. To set the length 
before a write operation, the length of the data 
contained in a field defined by this keyword in 
DDS can be accessed as required by your 
program. If your program combines the write 
operation with an input operation (for example, 
write-with-invite), SNUF sends a turnaround indi- 
cation and performs the input operation. If your 
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program issues a write-with-invite, it must issue a 
read or read-from-invited-program-devices opera- 
tion to receive the data from SNUF. Use the timer 
function to limit the waiting time for the read-from- 
invited-program-devices operation. 


If your program does not combine the write opera- 
tion with an input operation (write, write with end- 
of-group, or write with detach), SNUF sends one 
data record to the remote system for each write 
operation. 


If an error occurs while sending your data, SNUF 
notifies your program with a return code on the 
current write operation, and the data is not sent. 


End-of-Group Function 


Your program uses the end-of-group function to 
indicate that this is the last record in a chain of 
records. The end-of-group function does not indi- 
cate, however, that your program is ready to 
receive data. Use the DDS keyword allow write 
(ALWWRT) to indicate that your program has fin- 
ished sending data and now wants to retrieve data 
from the host system. 


Function-Management-Header 
Function 


You can send a function management header (FM 
header) with a write operation. A function man- 
agement header is valid only with the first record 
in a chain. SNUF checks whether the function 
management header is allowed, but does not 
check the function management header format or 
content. 


The function management header is a special 
record or portion of a record that contains control 
information for the data that follows. The first byte 
of the record defines the length of the header. 
The length is specified in hexadecimal and 
includes the length byte. The header portion 
immediately follows the length byte. 


When your program receives a function manage- 
ment header, the action SNUF takes depends on 
the header processing (HDRPROC) parameter of 
the ADDICFDEVE or OVRICFDEVE commands. 

If you specified HDRPROC(*SYS), SNUF removes 
the function management header and places any 
user data in the record area. If you specified 
HDRPROC(*USER), SNUF places the function 
management header in the record area. The 


return code indicates that a function management 
header was received. To receive any data that 
accompanied the FM header, issue a second input 
operation. 


When a session started by a program start 
request receives a function management header, 
SNUF examines the FM header for hex 
0542000001, which is the standard IMS/VS func- 
tion management header. This function manage- 
ment header does not contain function 
management information and is not placed in the 
record area. If the function management header 
is not hex 0542000001, SNUF passes it to the 
application program as the first input. To get any 
additional data that accompanied the program 
start request, issue a second input operation. 


Receiving Data 


Two operations can be issued to receive data: 
read and read-from-invited-program-devices. Use 
the read operation to receive data from a specific 
program device, and use the read-from-invited- 
program-devices operation to read from any previ- 
ously invited program device. Use the invite 
function to request data from a specific remote 
program. 


Read Operation 


Your program uses the read operation to obtain 
data from a specific program device. In a commu- 
nications session, the operation causes SNUF to 
read data from the remote program with which 
your program is communicating. Your program 
does not receive control until the data is available. 


The record that your program receives depends 
on the BATCH parameter of the ADDICFDEVE or 
OVRICFDEVE commands. If you specify 
BATCH(*NO), SNUF assembles each physical 
record into a logical record until it reaches the 
end-of-group indicator. Your program can perform 
record selection at the time a data record is 
received, based on the content of a portion of the 
record. Use the DDS keyword RECID to specify 
this selection value. 


To check for an end-of-group indication sent by 
the host system, test a response indicator associ- 
ated with the DDS keyword RCVENDGRP or test 


for one of the return codes listed under “Receive- 
End-of-Group” on page 4-14. 


To check for a function management header on 
the first record of a chain of records, check for 
one of the return codes listed under “Receive- 
Function-Management Function” on page 4-14 or 
test a response indicator associated with the DDS 
keyword RCVFMH. If your program has received 
a function management header, your program 
must issue another read operation to obtain the 
data associated with that function management 
header. 


Your program does not always receive data after 
an input request. In certain instances, only a 
return code is set to indicate a change in the oper- 
ating state of a session. Test for a turnaround 
indication sent from the host system by testing a 
response indicator associated with the DDS 
keyword RCVTRNRND or by checking the return 
code. 


Invite Function 


Your program uses the invite function to request 
input data from a specific remote program. Your 
program receives control without waiting for the 
input. To obtain the data, your program must 
issue a read or read-from-invited-program-devices 
operation later in the transaction. 


You can issue the invite function alone or in com- 
bination with another function. 


Read-From-Invited-Program-Devices 


Operation 


Your program can use the read-from-invited- 
program-devices operation to perform the fol- 
lowing functions: 


¢ Obtain data from any remote program that has 
responded to an invite function previously 
issued in your program. lf data becomes 
available to your program from more than one 
remote program before the read-from-invited- 
program-devices operation is issued, your 
program receives the data that was first made 
available from a remote system. 


e Verify that the time interval established by the 
timer function has run out, and if it has, 
ensure that your program is notified. Fora 
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description of the timer function, see “Timer 
Function” on page 4-12. 


All read-from-invited-program-devices operations 
should be issued to receive data after an invite 
function is issued by itself or in combination with 
another operation, or after a timer function is 
issued. The operation can receive any of the 
same return codes as the read operation. 


Waiting for a Display File, an ICF 
File, and a Data Queue 


Use data queues when a program must wait for a 
display file, an ICF file, and a data queue, in any 
combination, at the same time. The following 
commands are used with the specified DTAQ 
parameter: 


¢ Create Display File (CRTDSPF) 

e¢ Change Display File (CHGDSPF) 
¢ Override Display File (OVRDSPF) 
¢ Create ICF File (CRTICFF) 

¢ Change ICF File (CHGICFF) 

¢ Override ICF File (OVRICFF) 


Use these commands to indicate a data queue 
that will have entries placed in it when one of the 
following occurs: 


e An enabled command key or Enter key is 
pressed from an invited display device. 

¢ Data becomes available when the session is 
invited for an ICF device. 

e A user-defined entry is made to a data queue 
by a job running on the system. 


For more information, see the CL Programming 
book and the ICF Programming book. 


Notifying the Remote Program of 
Problems 


Use the fail, cancel, and negative-response func- 


tions to inform the host application program of any 
errors in data being sent or received. 


4-10 SNA Upline Facility Programming V4R1 


Fail Function 


The fail function causes different indications to be 
sent to the host system, depending on the current 
state of your program. 


e lf your program is in a send state, SNUF 
sends a cancel indication to the remote host 
system. Any data not sent in the current 
transmission chain is discarded. 


e lf your program is in a receive state or if fail is 
the first function issued after receiving an end- 
of-group (chain) indication, SNUF sends a 
negative-response indication to the remote 
host system. 


Cancel Function 


Your program uses the cancel function to cancel 
the current chain of data it is sending to the 
remote program. The cancel function informs the 
remote program that it is abnormally ending the 
current data chain. The receiving program should 
disregard all records received since the last end- 
of-group (chain) indication. 


The cancel function is valid only under the fol- 
lowing conditions: 


e¢ While your program is in a send state. 


e In achain of records. You cannot cancel a 
chain after sending the end-of-group indi- 
cation. 


e In batch sessions. In batch sessions, a chain 
may contain several records. 


Your program receives an error return code if it 
issues a cancel function in a session specified as 
BATCH(*NO) on the ADDICFDEVE or 
OVRICFDEVE commands. It also receives an 
error return code if it issues a cancel function 
between chains or in receive state. 


The cancel function does not end the session. 
The host system can perform error recovery after 
receiving the cancel indication. To determine the 
recovery action the host system takes, issue an 
input operation after your program issues a cancel 
function. 


The host system can also send a cancel indication 
to your program. To check for a cancel sent from 
the host system, check for return code 8330 or 


8331, or test a response indicator associated with 
the DDS keyword RCVCANCEL. 


Negative-Response Function 


Your program uses the negative-response function 
when it detects an error with the data it received. 


Issue the negative-response function when your 
program is in the receive state, the data received 
is in a chain, or the function is the first function 
after the end of a chain. 


When your program sends a negative-response 
indication to the program that sent the data, it may 
include eight characters of sense code, which indi- 
cates the reason for the negative response. 


The eight characters of sense code are coded as 
user data in your program output buffer. The first 
four characters in the buffer are the system sense 
code; the last four characters are the user sense 

code. 


The system sense code must be one of the fol- 
lowing: 10xx, 08xx, or 0000. SNUF checks the 
system sense code and rejects the operation if it 
is not one of the specified codes. If the program 
does not supply a system sense code, the system 
uses the default code of 0811 (break). The sup- 
ported SNA sense codes are described in the 
Systems Network Architecture Formats book. 


Your program can also receive a negative- 
response indication from the host system. To 
check for a negative response received from the 
host system, check for return code 8319 or test a 
response indicator associated with the DDS 
keyword RCVNEGRSP. 


Using Additional Functions and 
Operations 


Your program can use the get-attributes operation 
and the respond-to-confirm, request-to-write, 
cancel-invite, and timer functions with SNUF com- 
munications. 


Respond-to-Confirm 


Use the respond-to-confirm (RSPCONFIRM) 
keyword to send a positive response to a received 
definite response request. The respond-to-confirm 
function can be used only when a definite 
response request is outstanding. You can check 
the major and minor return codes or use the 
RCVCONFIRM indicator to determine when to 
issue a respond-to-confirm function. After sending 
the response, your program can continue pro- 
cessing as indicated by any other information 
received. 


Request-to-Write Function 


Your program uses the request-to-write function to 
indicate that it wants to send data to the remote 
program. When the remote program receives the 
request-to-write indication, it decides whether to 
stop sending data and when to stop. 


After issuing this function, your program should 
continue to receive data until it receives a return 
code indicating the remote program is ready to 
begin receiving. (In some cases, the remote 
system may decide not to receive data and thus 
does not send a turnaround indication.) In 
response to the return code, begin sending data, 
perform other processing, or end your program. 


Issue the request-to-write function only during a 
transaction and only when your program is in the 
receive state. If your program is neither receiving 
nor sending (that is, if it is between transactions), 
issuing the function has no effect and an 8327 
code is returned to your program. 


If the remote program sends a request-to-write 
indication, your program receives return code 
0010 at the end of a write operation. If your 
program receives this return code, stop sending 
data and issue an input operation as soon as pos- 
sible. 


Cancel-Invite Function 


Your program uses the cancel-invite function to 
cancel any invite function which has not received 
any input from any invited session. The cancel is 
handled by SNUF on the AS/400 system; no 
command or data is sent to the host system. 


Chapter 4. Writing SNUF Application Programs 4-11 


If data or a message is being received from the 
remote system when the cancel-invite function is 
initiated, the cancel-invite function fails and return 
code 0412 is received by your program. Your 
program must issue input operations to receive 
the data until it receives return code 0300 or 0308. 


Timer Function 


Your program can use the timer function before 
doing specified functions, such as a read-from- 
invited-program-devices operation. The timer 
function specifies an interval of time (in hours, 
minutes, and seconds) to wait before your 
program receives a return code of 0310 (timer run 
out). 


Use the timer function to set the timer interval. 
The timer function is issued on an output opera- 
tion to a record that has the record level keyword 
TIMER specified. 


When a timer is set and your program requests 
data from a previously invited device, if data is 
available, your program receives the data along 
with a return code indicating a successful opera- 
tion. If an error occurs, your program receives a 
return code describing the error. If the timer runs 
out before the data is received, return code 0310 
is received by your program and the session 
remains invited. 


Another way to specify the time interval is with the 
WAITRCD parameter on the CRTICFF, CHGICFF, 
OVRICFF commands. The WAITRCD parameter 
establishes the maximum time interval used for all 
read-from-invited-program-devices operations 
issued for the ICF file. 


When the timer function is in effect, the value 
specified for the WAITRCD parameter is ignored. 


Only one timer interval can be maintained for a 
program. If you set a new timer before an existing 
timer has run out, the new timer replaces the old 
one. 


Note: For ILE RPG/400 programs, a timer func- 
tion is not valid unless at least one session is 
attached to your program. 
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Get-Attributes Operation 


Your program uses the get-attributes operation to 
determine the status of the current session. You 
can issue it at any time during the session. The 
operation gets the current status information about 
the session in which your program is communi- 
cating. 


Ending a Transaction 


A communications transaction can be ended by 
your program or by the program at the remote 
system. 


Communications with the remote program ends 
when your program ends the transaction; 
however, the session may still exist: 


e If your program acquired the session, either 
the AS/400 system or the host system can 
start another transaction in this session. 


e If the host system acquired the session and 
your program ends the transaction, the remote 
system can issue another program start 
request to the AS/400 system. To begin 
another transaction from the AS/400 system, 
you must open or acquire a new session. 


Detach Function 


A transaction is ended with the detach function. 
The detach function informs the other program 
that your program is done sending data and has 
ended the transaction. The detach function is only 
supported in half-duplex flip-flop mode. 


You can combine the detach function with either 
an evoke function or a write operation. 


Ending a Session 


A communications session is ended with either the 
release operation or the end-of-session function. 
You should primarily use the release operation 
because the release operation ends the session 
only if all processing is complete. 


The end-of-session function always ends the 
session; therefore, it should be used only when 
you want to force the session to end. 


Release Function 


Your program uses the release function to end a 
session. This operation ends the session unless 
an error condition occurs (in which case, the 
release operation is not successful). To end the 
session unconditionally, use the end-of-session 
function. 


If your program issues a release operation during 
an active transaction, it receives an error return 
code. The system performs the release operation 
only after all data for the transaction has been 
sent or received. 


When your program issues a successful release 
operation, SNUF ends the session and frees the 
resources that were used by your program. The 
logical unit is made available to other programs in 
the system wanting to acquire the session or for 
another program start request from the host 
system. 


End-of-Session Function 


Your program uses the end-of-session function to 
end a session. The end-of-session function ends 
the session and always gives a normal completion 
return code. If your program uses the keyword 
during an active transaction, SNUF abnormally 
ends the transaction and the session, and possibly 
the remote program as well. However, your 
program still receives a normal completion code. 
You can use this function when an error occurs on 
a previous function and your program cannot 
easily recover. 


When a program started by a program start 
request receives a detach return code, end the 
program or issue an end-of-session function. This 
leaves the session and remote program available 
for other transactions. 


Note: A positive response is sent before the 
session is ended normally if the previous opera- 
tion received an end-of-chain indication and a 
response is required. Negative responses are 
sent to the chains that are partially received by the 
user program, or if the session is ended by the 
system. 


Using Response Indicators 


Response indicators are defined to your program 
in the ICF file and are set on each input operation. 


However, these indicators are optional, and major 
and minor return codes can also be used to indi- 
cate the status of input operations. 


Receive-Cancel 


Your program uses the receive-cancel response 
indicator to determine if the remote program can- 
celed the current chain. 


Receipt of a cancel request is also indicated by 
major return code 83 (session error) and minor 
return codes 30 (cancel with change-direction) or 
31 (cancel without change-direction). 


The cancel notification is always received without 
user data. 


Receive-Confirm 


Your program uses the receive-confirm response 
indicator to determine if the remote program sent 
an end-of-chain indication with the definite 
response request. 


Receipt of a confirm request is also indicated by 
major return code 00 (user data received) and 
minor return code 03 (end of group received). 


Receive-Detach 


Your program uses the receive-detach response 
indicator to determine if the remote program has 
ended a transaction (the detach request has been 
received). The receive-detach function is only 
supported in half-duplex flip-flop mode. 


The presence of the detach request is also indi- 
cated by major return codes 00 (user data 
received), 02 (user data received but program is 
being canceled), or 03 (no data received), and 
minor code 08 (detach received). 
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Receive-End-of-Group 


The receive-end-of-group response indicator is 
used by your program to determine if your 
program has received the last record in a group 
(chain). 


The presence of the end-of-group function is also 
indicated by major return codes 00 (user data 
received), 02 (user data received but program is 
being canceled), or major return code 03 (no data 
received) with minor return codes 03 or 07. 


Receive-Function-Management 
Function 


Your program uses the receive-function manage- 
ment header response indicator to determine that 
function management header data was received 
from the host program. 


The presence of function management header 
data is also indicated by major return code 00 
(user data received) with minor return codes 04, 
05, or 07, or major return code 02 (user data 
received but program is being canceled) and 
minor return codes 04, 05, or 07. 


Receive-Negative-Response 


Your program uses the receive-negative-response 
indicator to receive an indication that the other 
program encountered an error when it was 
receiving data. 


Receipt of a negative-response function is also 
indicated by a return code of 8319. 


Receive-Turnaround 


Your program uses the receive-turnaround 
response indicator to receive an indication from 
the other program that it is ready to receive data. 


Receipt of a turnaround function is also indicated 
by return codes 0000 (user data received), 0200 
(user data received but program is being can- 
celed), or 0300 (no data received). 
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Using the Input/Output Feedback 
Area 


The results of input/output (I/O) operations are 
communicated to the program using the return 
codes, messages, and I/O feedback information. 
The area is changed for each I/O operation and 
consists of a common I/O area and a file- 
dependent I/O area. 


Offset 48 in the file-dependant I/O feedback area 
applies to SNUF and indicates whether the remote 
program has requested permission to send data. 
For general information about the I/O feedback 
areas, see the book, ICF Programming. 


Using Return Codes 


After each operation, an ICF return code is 
returned to your program. Your program should 
check this return code to determine: 


e The status of the operation just done 
e The operation that should be done next 


For example, a major return code of 00 indicates 
that data was received. Along with this major 
code, you can receive from SNUF, for example, 
one of the following minor codes: 


e 01: Indicates that your program should con- 
tinue receiving data. 


e 08: Indicates that the remote program has 
ended the transaction. Your program can do 
one of the following: 


— lf your program acquired the session, 
issue another evoke function or end the 
session. 


— lf the session was acquired by a program 
start from the remote system request, end 
the session and continue local processing 
or end the job. 


Another example would be a major code of 83. In 
this case either the local system, remote system, 
or remote program has detected an error that may 
be recoverable. Different minor codes can be 
returned just as for the 00 major code. For 
example, if your program receives a minor return 
code of E8, your program has used a cancel-invite 
function in a session that was not invited. The 
cancel-invite function is only valid when it is used 


after a valid invite function. For this return code, 
your program is responsible for the necessary 
error recovery. The session and transaction are 
still active, and you can recover from this error by 
correcting the error in your program before trying 
to communicate with another program. 


It is recommended that your program check the 
ICF return codes at the completion of every opera- 


tion to ensure that the operation completed suc- 
cessfully or, if not, that the appropriate recovery 
action is taken. 


See Appendix B for a description of the return 
codes that can be returned to your application 
when it is using SNUF. 
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Chapter 5. Considerations for SNUF 


This chapter discusses programming consider- 
ations for application programs that provide com- 
munications between the AS/400 system and a 
host system. It examines programming topics for 
the AS/400 system programmers, and program 
start request formats for both the host and AS/400 
system. See Appendix C for information needed 
by the host programmers to communicate through 
SNA upline facility (SNUF). 


General Considerations 


The following topics apply to both CICS/VS and 
IMS/VS host systems. They describe information 
needed by the AS/400 SNUF programmer while 
writing programs that communicate with either 
CICS/VS or IMS/VS. These topics also apply to 


both half-duplex flip-flop and half-duplex con- 
tention modes. This section is followed by a dis- 
cussion of contention mode (see “Contention 
Mode Considerations” on page 5-4). 


Half-Duplex Communications 


Communication between an AS/400 program and 
a host system program occurs in either half-duplex 
flip-flop or contention modes, with one program 
sending at a time. When the sender wants to 
become the receiver, it sends a turnaround indi- 
cation. 


While sending, your program can cause a turn- 
around by issuing an input operation. SNUF inter- 
prets the input operation and sends the 
turnaround indication, as shown in Figure 5-1. 


AS/400 IMS/VS or IMS/VS or CICS/VS 
Application SNUF CICS/VS Application Program 
Write i> Data > 
Write i> Data > 
Read +> No data with . 
change direction 
| 
RV2W531-0 
Figure 5-1. Sending Data in Half-Duplex Mode 
To make more efficient use of the communications 
line, use write-with-invite to send a turnaround 
indication, as shown in Figure 5-2. 
AS/400 IMS/VS or IMS/VS or CICS/VS 
Application SNUF CICS/VS Application Program 
Write i> Data > 


Write with Invite 


——> Datawith change 


| direction 


Read « ;- Data < 
| 


RV2W532-0 


Figure 5-2. Sending a Change-Direction Indication in Half-Duplex Mode 


If your program is receiving and must send data, 
use the request-to-write function. This causes 
SNUF to request that the current sender send a 
turnaround indication as soon as possible. If your 
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program is sending data and receives a request- 
to-write return code, perform an input operation as 
soon as possible. 
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Sending Records in Chains 


The request/response unit (RU) size parameter in 
the BIND command limits the size of a request 
unit that two logical units can send to each other. 
In order to send a request that contains more 
information than will fit into one RU, logical units 
divide the information into a series of separate 
requests. This series of related requests is called 
achain. You determine the maximum length of 
an RU during host system generation. 


How your program processes chains is deter- 
mined by the type of session you specify: either 
an interactive or a batch session. You choose the 
type of session by specifying BATCH(*NO) or 
BATCH(*YES) on the ADDICFDEVE or 
OVRICFDEVE command. 


The RU size parameter is ignored for a program 
started by a program start request. The program 
is treated as though BATCH(*YES) was specified. 


Interactive Sessions: If you specify 
BATCH(*NO), each output operation is considered 
a logical record and is written as a separate chain. 
For input operations, SNUF assembles elements 
of a chain into one logical record until it reaches 
the end-of-group indication or the maximum record 
length. If SNUF reaches the maximum record 
length before it reaches the end-of-group indi- 
cation, return code 81B9 is passed to your 
program and the session ends abnormally. 


For output operations, SNUF sends each logical 
record as a chain. If the length of the logical 
record exceeds the size of the RU, a chain of 
request units is used to send the data. If the 
length of the logical record does not exceed the 
size of the RU, a single RU, with begin- and end- 
chain indicators, is sent. 


The effect of chaining on the host IMS/VS or 
CICS/VS system must also be considered. If the 
host is not configured to assemble the chain of 
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request/response units into a logical record, the 
host application programmer will be responsible 
for the task. 


The following SNUF communications functions are 
not valid in interactive sessions: 


¢ Cancel 
¢ Cancel with invite 


Figure 5-3 on page 5-3 shows how SNUF uses 
chains when you specify BATCH(*NO) and set the 
maximum request unit size to 256. 


Batch Sessions: If you specify 
BATCH(*YES), SNUF does not attempt to distin- 
guish logical records. For input operations, SNUF 
passes an RU for each read to the application 
program, which must determine the logical 
records. Therefore, while operating with 
BATCH(*YES), your program should check for an 
end-of-group return code. 


Normally, when your program issues write oper- 
ations and then performs an input operation or 
ends the transaction, it sends an end-of-group 
indication. In these cases, SNUF automatically 
ends the chain. When operating with 
BATCH(*YES), your program may want to send 
an end-of-group indication without sending a turn- 
around indication or without ending the trans- 
action. For example, you may want your program 
to break data streams into smaller units that can 
be recovered. To accomplish this, issue a write- 
with-end-of-group function. 


If your application uses the timer function, set the 
timer to the time: 


e It will take the host to send, or 

e For the AS/400 to receive all of the elements 
of the chain (first in chain, middle in chain, 
end of chain). 


When the entire chain is received by SNUF, the 
chain can be retrieved by the application by using 
multiple READ operations. 


AS/400 CICS/VS or CICS/VS or IMS/VS 
Application Program SNUF IMS/VS Application Program 
| | 
Write with Invite | 
AA ---A|BB ---B }-+—> | 
256 512 |! 
| | 
[AA ++: A > 
i Startofchain 
|) BB...B > | 
| Endofchain | 
AA ---A BB B |+—+ 
«—+{CC:--C|DD -:-D | 
256 512 
| < CC -::C | 
| Startof chain | 
Read | ] DD .....« D | 
| Endof chain 
4— 1G 6) BB+ 0D 
| | 
RSLS152-7 
Figure 5-3. Chaining in an Interactive Session — BATCH(*NO) 
Figure 5-4 shows how SNUF handles chaining 
when you specify BATCH(*YES). 
AS/400 CICS/VS or CICS/VS or IMS/VS 
Application Program SNUF IMS/VS Application Program 
| 
Write | 
AA ---A LAA ---A | ‘a 
| Startofchain | 
Write | 
BB --- B }—————_> | BB - - -B > 
Write with Invite | | 
cc ...c }—_——_4|cCc :::¢ > 
| Endofchain | 
Read < XX ---X |e XX ++ +X 
Startof chain 
Head: 4 YY = + ¥ }#————1YY 1 Y 
Endofchain 
| | 
| | 


Figure 5-4. Chaining in a Batch Session — BATCH(*YES) 


Receiving Messages from the 
Host System 


SNUF can receive messages from both CICS/VS 
and IMS/VS. These messages inform SNUF and 
your program of key events occurring in the 
session. CICS/VS and IMS/VS send their mes- 
sages in the following arrangement: 


e For CICS/VS: DFHccnn text 


RSLS153-8 


e For IMS/VS: DFSccnn text 


For CICS/VS, DFH identifies the message, and 
ccnn represents the message number as 
described in the CICS/VS Messages and Codes. 
For IMS/VS, DFS identifies the message, and 
ccnn represents the message number as 
described in the IMS/VS Messages and Codes 
Reference Manual. See the appropriate book for 
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additional information about the received 
message. 


When SNUF receives a host system message, it 
waits for your program to receive it on the next 
operation. If the next operation is an input opera- 
tion, the message is returned to the input buffer of 
your program, and a return code is sent to your 
program to indicate that there is a message in the 
input buffer. If the next operation is not an input 
operation, the operation is rejected with a return 
code that indicates a message or data is waiting. 
In this case, your program must issue an input 
operation to get the message text. Until you 
receive the message, SNUF rejects any output 
operations. 


CICS/VS and IMS/VS messages may be greater 
than the length of your program input buffer. If 
this occurs, SNUF truncates the message on the 
right and passes your program a return code indi- 
cating the truncation. 


Session Recovery 


Protected sessions can be successfully started 
again after communications line failures. You 
define a protected session by specifying 
MSGPTC(*YES) on the ADDICFDEVE or 
OVRICFDEVE commands. When SNUF starts 
the session again, it exchanges information with 
the host system about the last messages sent and 
received. SNUF uses this information to deter- 
mine whether any data must be sent again. 
Therefore, to correctly start a protected session 
again, you must also define the host system 
session and transaction as protected. For 
CICS/VS host systems, specify the 
TYPE=OPTGRP parameter on the DFHPCT 
macro. For IMS/VS host systems, specify the 
INQUIRY parameter on the TRANSACT macro. 


With a protected session, when a line error occurs 
SNUF tries to start the session again. If the 
session does not start again successfully, return 
code 8191 is passed to your program. If SNUF 
successfully establishes the session again, the 
session resumes at the point of failure. 
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Contention Mode Considerations 


Communications between an AS/400 system 
program and a host system program can occur in 
half-duplex contention mode. The following is pre- 
sented to help explain the differences between 
half-duplex flip-flop and contention modes. 


e When communicating in flip-flop mode, the 
session is in contention state after the end- 
bracket. When communicating in contention 
mode, the session is in contention state after 
the end-chain. 


e When in contention, SNUF is the contention 
winner. 


¢ Since begin-bracket or end-bracket protocol is 
not used when communicating in contention 
mode, EVOKE, DETACH or RCVDETACH 
functions are not supported. 


e The first request (RU) after the BIND 
command is treated as a program start 
request. The program start request formats 
described in Figure 5-5 on page 5-6 and 
Figure 5-6 on page 5-6 are also applicable in 
half-duplex contention mode. The session 
should be ended and then restarted to run 
another program on the AS/400 system. 


Performance Considerations 


The following suggestions can help you get better 
performance in sessions using SNUF: 


¢ Combine input operations with output oper- 
ations. For example, use evoke-with-invite. 


¢ Specify a nonprotected session with 
MSGPTC(*NO) on the ADDICFDEVE or 
OVRICFDEVE commands. Nonprotected ses- 
sions require less line activity than protected 
sessions; however, no session recovery is 
provided by SNUF. 


e Specify an RU size large enough to contain 
the largest record to be sent or received. 
Specify the RU size as large as the value 
specified for the maximum user record length. 
Larger RU sizes may improve performance. 
For more information on blocking, see the 
book, Communications Management. 


e Specify a proper pacing count. If pacing is 
needed, seven is the best pacing count, as 


values above this might not improve perfor- 
mance. For more information on pacing 
counts see the book, Communications Man- 
agement. 


e The host system configuration parameters 
MAXDATA, MAXOUT, and PACING, the 
BFRS Group Macro parameter, and the 
PASSLIM Build Macro parameter can affect 
communications performance. For more infor- 
mation, see “Performance Considerations” on 
page C-5. 


Program Start Requests 


For a program on a CICS/VS or IMS/VS remote 
system to start a program on the AS/400 system, 
the remote program must send a program start 
request to the AS/400 system after you have 
started communications between the two systems. 
The program started by the program start request 
must run on a device you specify at configuration 
time as being program start request capable. 


When SNUF receives a program start request, it 
determines if the job should be run in the 
System/36 environment. If a System/36 proce- 
dure cannot be found SNUF starts the job in the 
OS/400 environment. For compatibility, the 
formats *TXTC, *TXTX, *EXEC, and *“EXEX can 
be used to start a job in either the System/36 or 
the OS/400 environment. The following sections 
only consider the OS/400 environment. For 
running jobs in the System/36 environment, see 
the System/36 Environment Programming. 


Communicating programs started by the host 
system (by the *EXEC, *EXEX, *TXTC, or *TXTX 
program start request) are treated as if BATCH 
(*YES) is specified. This means that each input 
request from the AS/400 program is satisfied with 
one element of a chain instead of requiring the 
entire chain. The end-of-chain return code is set 
when the last element of the chain is received, if it 
is not overridden by the end-of-transaction or 
change-of-direction return code. 


Note: For general information on writing pro- 
grams to be started by a program start request, 
see the book, /CF Programming. 


Formats of the Program Start Request: 
CICS/VS and IMS/VS on a remote system can 
send four different program start request formats: 


Format 
*TXTC 


Description 


This format starts a session in which 
CICS/VS or IMS/VS can send more 
than one record to the same program 
on the AS/400 system before the 
session is ended. 


*TXTX This format starts a session in which 
the request statement is the only 

source of data for the program or it is 
the only source of parameters for the 


program. 


*EXEC This format functions the same as the 
*TXTC format but is used for 


System/36 compatibility only. 


*EXEX This format functions the same as the 
*TXTX format but is used for 


System/36 compatibility only. 


The *TXTC and *TXTX formats allow you to use 
up to a 10-character program name and library 
name. The “EXEC and *EXEX formats allow only 
an 8-character program name and library name. 
The *EXEC and *EXEX formats are the same 
formats used on the System/36 and are included 
for use by CICS/VS and IMS/VS programs which 
formerly communicated with System/36 programs 
using SNUF. Use the *EXEC and *EXEX formats 
for applications requiring compatibility with 
System/36, and use the *TXTC and *TXTX 
formats for all other applications. 


The program start request identifies which 
program is to be started. The request can include 
up to 119 bytes of parameters if the format is 
“EXEX or “EXEC, and 218 bytes of parameters if 
the format is *TXTX or *TXTC to be passed to a 
program. In the System/36 environment, these 
parameters can be treated as data and received 
by the application program using the first read. 


A program start request must be on the first 
request unit (RU). Once the AS/400 program 
receives all the data, issue an end-of-session 
function. Otherwise, the session does not end 
until the AS/400 program ends. 


A session started by IMS/VS with a program start 
request can pass data or parameters with the 
request but it cannot receive data from the AS/400 
system. Similarly, a program on the AS/400 
system can receive data from IMS/VS ina 
remotely started session but cannot send data. 
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Keep the session active until the AS/400 program 
receives the data and a detach return code. Then 
end the session or end the program. To have the 
AS/400 program communicate further with 
IMS/VS, include an OVRICFDEVE command and 
issue an acquire operation to acquire a new 
session with IMS/VS. 


The begin-bracket (in half-duplex flip-flop mode) 
and first-of-chain indicators must accompany the 
program start request. If the program start 
request is a detach (*TXTX, *EXEX) request, end- 
bracket (in half-duplex flip-flop mode) and end-of- 
chain indicators must also accompany the request. 


The host system must send a BIND command to 
logical units reserved for program start requests 
on the AS/400 system. Use the VTAM VARY 
command with the LOGON option, the LOGAPPL 
parameter in the VTAM definition, or the appro- 
priate host system procedure (CICS/VS ACQ 
master terminal command or the IMS/VS 
/OPNDST command). After a detach return code, 
the AS/400 program should issue the end-of- 
session function so other program start requests 
can be handled. 


A program started by a program start request is 
always run in batch mode. It is treated as if 
BATCH(*YES) is specified on the ADDICFDEVE 
command. 


Syntax of the Program Start Request Siate- 
ment: The type of program start request (“EXEC, 
“EXEX, *TXTX, or *TXTC) must begin in position 

1 of the program start request statement. If the 
type begins in any other position, SNUF starts the 
default program instead of the program named in 
the statement. 


The syntax of the program start request statement 
is shown in the following diagram: 


*TXXx or *EXxx program name 
‘i TL a 
| parameters | | user identifier | 
L Jk J 


r levy te 7 
| library name | | user password | 
L de LE J 


Figure 5-5 describes each parameter for a 
program start request type of *TXTX or *TXTC. 


Figure 5-5. Parameters for the Program Start Request (*TXTX, *TXTC) 


Coding Positions Field 


Description 


1 through 6 *TXTX, Type of program start request being used to start a program on 
*“TXTC the AS/400 system. Position 6 must be a blank. 
7 through xx Program The name of the program to be started on the AS/400 system. 
name The name must be 1 to 10 characters long. One or more blanks 
must follow the name. 
xx through 226 Parameter Parameter for the program started. This field begins with the first 
nonblank character following the program name. 
227 through 236 User ID The user ID (name) of the AS/400 user whose program is being 


started. If security is active on the AS/400 system, this ID must 
be defined on the system. 


237 through 246 Library name 


started. 


247 through 256 User pass- 


word started. 


The name of the AS/400 library that contains the program to be 


The password of the AS/400 user whose program is being 


Figure 5-6 on page 5-6 describes each parameter 
for a program start request type of *EXEX or 
“EXEC. 
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Figure 5-6. Parameters for the Program Start Request (“EXEX, *EXEC) 


Coding Positions Field 


Description 


1 through 6 *EXEX, Type of program start request being used to start a program on 
“EXEC the AS/400 system. Position 6 must be a blank. 
7 through xx Program The name of the program to be started on the AS/400 system. 
name The name must be 1 to 8 characters long. One or more blanks 
must follow the name. 
xx through 127 Parameter Parameter for the program started. This field begins with the first 
nonblank character following the program name. 
128 through 135 User ID The user ID (name) of the AS/400 user whose program is being 


started. If security is active on the AS/400 system, this ID must 
be defined on the system. 


136 through 143 Library name 


The name of the AS/400 library that contains the program to be 


started. 
144 through 147 User pass- The password of the AS/400 user whose program is being 
word started. The password must contain 4 characters. If security is 


active on the AS/400 system, this password must be defined on 
that system and must be the correct password for the user ID 


specified. 


Note: The user ID, library name, and user pass- 
word fields are positional and must be padded on 
the right with blanks if another field follows. If 
security is not used on the AS/400 system, the 
user ID and password are not required. 


The program start request statement can contain 
parameters following the program name. Any 
parameter that follows the program name through 
position 127 if the format is ~EXEX or *EXEC, or 
position 226 if the format is *TXTX or *TXTC, is 
used by the program started on the AS/400 
system. If security is used, the remote system 
uses the positional parameters specified in posi- 
tions 128 through 147 for the formats *EXEX or 
“EXEC or positions 227 through 256 for formats 
“TXTX or *TXTC to pass security information to 
the AS/400 system. 


At least one blank must separate the program 
name that begins in position 7 from the data or 
parameters. If the AS/400 system uses security, 


1 7 


send the program start request as a 147-byte 
record if the format is *EXEX or *EXEC, and as a 
256-byte record if the format is *TXTX or *TXTC. 
Any unused positions should contain blanks. 


If the system does not use security and does not 
specify a library name, you do not need the three 
parameters in positions 128 through 147 for the 
formats *EXEX or *EXEC or positions 227 through 
256 for formats *TXTX or *TXTC. In this case, the 
length of the program start request depends only 
on the amount of data and the number of parame- 
ters to be passed to the AS/400 program. 


If a program was not started successfully, a nega- 
tive response with sense data is sent to the 
remote system. The sense data contains the 
reason code of the failure. 


Sample of a Program Start Request: 
Figure 5-7 shows a sample of the record format of 
a CICS/VS or IMS/VS program start request. 


237 247 


isi TIXiTIX! |S 


Pid UiiriBics |i 


Figure 5-7. Example Program Start Request Record Format 
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In Figure 5-7, the program start request starts the 
AS/400 program named S3XPROG and sends it 
three positional parameter values. The identifier 
of the AS/400 user whose program is being 
started is CI3X. The user’s password is J7PW. 
The S3XPROG program is located in the AS/400 
library named ULIBC. 


Prestart Jobs Considerations 


To minimize the amount of time required to carry 
out a program start request, you can use prestart 
jobs to start a job on your system before the 
remote system sends a program start request. 


To use prestart jobs, you need to define both 
communications and prestart job entries in the 
subsystem description, and make certain program- 
ming changes to the prestart job program with 
which the host program communicates. For infor- 
mation on using prestarted jobs, see the book, 
ICF Programming. 


Programming for CICS/VS 
Systems 


The following topics describe information needed 
by the AS/400 SNUF programmer while writing 
programs that communicate with CICS/VS. This 
information describes half-duplex flip-flop commu- 
nications. 


Evoke Considerations for a 
CICS/VS System 


When it communicates with CICS/VS, SNUF 
ignores the user ID, library name, and user pass- 
word parameters in the evoke function and sends 
the remote program name and the user data or 
program parameter. The first parameter is both 
the name of the CICS/VS program to be evoked 
and the CICS/VS transaction code. The name of 
the CICS/VS program is limited to four characters. 
SNUF does not send the user password, library 
name, or user ID parameters specified in the 
program evoke function. 


If the CICS/VS host system is using security, the 

first evoke function your program issues must start 
a sign-on (CSSN) transaction on the host system. 
You must include the required security information 
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with the evoke function. You also must specify 
the transaction code CSSN in the program name 
parameter and include the keyword parameters 
PS (user password) and NAME (user ID) as the 
program parameter. For additional information 
about the CSSN and sign-off (CSSF) transactions, 
see “SNUF Transaction Codes” and “Security 
Considerations.” 


SNUF Transaction Codes 


There are several transactions that an AS/400 
program can send to a CICS/VS system to start a 
particular remote program. An AS/400 program 
can use an evoke function to specify the CICS/VS 
service routine or application program to be 
started. The transaction codes in Figure 5-8 can 
be specified in the procedure name parameter of 
an evoke function. 


Figure 5-8. SNUF Transaction Codes 


Transaction 
Code Purpose of Transaction 


CSSN Starts a CICS/VS program that con- 
trols the security of a CICS/VS host 
system and allows the user of the 
AS/400 program to sign on to the host 
system. 


CSSF Starts a CICS/VS program that signs 
off a user who has finished communi- 
cating with the host system. 


Security Considerations 


CICS/VS provides security for the work station 
operator rather than providing security for the 
device used by the operator. The CICS/VS secu- 
rity support is handled by two CICS/VS trans- 
actions: CSSN (sign-on) and CSSF (sign-off). 
The CSSN and CSSF transactions are used only 
to start and end a session in which security pro- 
tects the transactions that occur in the session. 
SNUF can issue an evoke function to start the 
security transactions and the user transactions to 
be protected. User transactions must be started 
(with an evoke function) between the use of CSSN 
and CSSF transactions. 


For additional security, supply the password to the 
AS/400 system from an external source, such as a 
work station operator. 


CSSN Transaction: The CSSN (sign-on) 
transaction signs a user on to the CICS/VS host 
system. To evoke the CSSN transaction on a 
CICS/VS system with active security, the evoke 
function must include two security parameters. 
The parameters are user password ("PS"=) and 
user ID ("NAME"=), which are specified in 
keyword form and separated by acomma. The 
password can be 1 to 4 characters and the user 
ID can be 1 to 20 characters. 


The evoke function for the CSSN transaction 
always results in a reply from CICS/VS. To 
receive the reply message, your program must 
issue an input operation after it issues the evoke 
function. 


If an AS/400 program issues a successful CSSN 
evoke function, it must issue a CSSF evoke func- 
tion before it issues a release operation in that 
session. If the program issues a release opera- 
tion without a CSSF evoke, CICS/VS signs the 
user off the host system. 


CSSF Transaction: The CSSF (sign-off) 
transaction ends communications between your 
program and CICS/VS. The CSSF transaction 
also removes the previously specified password 
and name from the CICS/VS sign-on table. 


After the evoke function for the CSSF transaction 
has been completed, a CICS/VS message is avail- 
able to your program. Issue an input operation to 
receive the message. 


After a successful CSSF evoke function, the 
program can issue a CSSN evoke function to the 
same session or to another session. The function 
can use a different password and name each 
time. 


For more information about the CSSN and CSSF 
CICS/VS transactions, see the CICS/VS Supplied 
Transactions book. 


Programming for IMS/VS 
Systems 


The following IMS topics describe information 
needed by the AS/400 SNUF programmer while 
writing programs that communicate with IMS/VS. 
This information describes half-duplex flip-flop 
communications. 


Evoke Considerations for an 
IMS/VS System 


When communicating with IMS/VS, SNUF does 
not send the user identifier and library name 
parameters because they are not used by IMS/VS. 
SNUF sends the remote program name, the user 
password (if it is specified), and the user data or 
program parameters. If IMS/VS uses security, you 
must specify the user password in the parameter 
list. To send the user password to IMS/VS, you 
also must specify “IMS or *IMSRTR on the HOST 
parameter of the ADDICFDEVE or OVRICFDEVE 
command. 


Sending IMS/VS Commands 


The AS/400 program can send IMS/VS commands 
by using the write operation and placing the 
command at the beginning of the logical record 
buffer. The system can only send commands 
when the session is between transactions. The 
program should not send commands that alter the 
status of the logical unit (Such as the /ASSIGN 
command) because the results cannot be pre- 
dicted. 


IMS/VS Message Headers 


If you specify HDRPROC(*USER) on the 
ADDICFDEVE or OVRICFDEVE commands, 
SNUF passes IMS/VS message headers to the 
program in its input buffer. The program also can 
send message headers by using the function man- 
agement header function (see “Function- 
Management-Header Function” on page 4-8). 
Message headers can be used to pass message 
descriptors, component identification and control 
information. Additional information on message 
headers can be found in the IMS/VS Advanced 
Function for Communications book. 
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Security Considerations 


If IMS/VS requires password security from the 
AS/400 program, the AS/400 program can supply 
the password in the evoke parameter list. SNUF 
sends the password in the correct position on 
behalf of the user. For additional security, supply 
the password to the AS/400 program from an 
external source, such as a work station operator. 


Handling Errors 


When IMS/VS detects an error on a received 
message, it returns an exception response with 
sense data. SNUF notifies the AS/400 program 
that an error has occurred and that sense data is 
available. To receive the sense data and the 
status of the session, issue an input operation. 


The system sense bytes are either hex 0800 or 
hex 0826. The user sense bytes contain the 


IMS/VS error message number in hexadecimal 
form. For example, if the AS/400 program evokes 
an invalid transaction identifier, IMS/VS returns 
sense bytes of hex 08000040. This is converted 
and placed in the program buffer as the charac- 
ters DFS0064. 


Sending Transactions without 
Waiting for Output 


An AS/400 program can use the evoke-with- 
detach function to send a complete transaction to 
IMS/VS without waiting for output from the IMS/VS 
program. This capability allows the AS/400 
program to send several transactions before 
receiving a reply from IMS/VS. 


An order entry application uses this type of pro- 
cessing, as shown in Figure 5-9. The evoke-with- 
detach function also allows the program to evoke 
a transaction in which the program reply is sent to 
another session, such as a program start session. 


AS/400 IMS/VS 

Application SNUF IMS/VS Application Program 
Evoke with Detach —> Message j—> 

Evoke with Detach — > Message —> 

Read ¢ : : Reply 

Read * I Reply 


RV2W533-0 


Figure 5-9. Sending Transactions without Waiting for IMS Output 


The processing may differ slightly if you specified 
HOST(*IMSRTR) on the ADDICFDEVE or 


OVRICFDEVE command, as shown in 
Figure 5-10 on page 5-10. 


AS/400 IMS/VS 
Application SNUF IMS/VS Application Program 
Evoke with Detach st Message |p 
Read +» Ready to receive {> 
— '—DFS290 
Evoke with Detach a Message | > 
Read ++ Ready to receive i—> 
< Reply 
Read > | 
— ;— Reply 
| | 


RV2W534-0 


Figure 5-10. Sending Transactions without Waiting for IMSRTR Output 
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Requesting Messages with the 
Ready-to-Receive Command 


The SNA ready-to-receive (RTR) command can 
be used to request any messages waiting on the 
IMS/VS output queue for this session. Before you 
send this command, you must specify 

HOST (*IMSRTR) on the ADDICFDEVE or 
OVRICFDEVE command. SNUF issues the RTR 
command when the AS/400 program issues an 
input operation (read) between transactions. 


If a message exists on the IMS/VS output queue 
when SNUF sends the RTR command, IMS/VS 
sends the message. If no messages exist on the 
output queue, IMS/VS sends system message 
DFS290, which indicates the queue is empty. 
SNUF passes the DFS290 message to the 
AS/400 program with return code 0028, indicating 
a system message with a detach indication was 
received. If you expect more data, continue with 


other processing and try the input operation again 
later. 


If you specified HOST(*IMS) on the ADDICFDEVE 
or OVRICFDEVE command, the AS/400 program 
must wait until output is available before it can 
complete the input operation. 


Operating in Terminal Response 
Mode 


Terminal response mode is an operation method 
defined for transactions and terminals attached to 
IMS/VS. When an IMS/VS logical terminal 
(LTERM) operates in terminal response mode, 
each transaction evoked must have a reply before 
the next transaction can be evoked. 


Figure 5-11 on page 5-12 shows how an inquiry 
program on the AS/400 system starts an inquiry 
program on the IMS/VS system. The figure shows 
both terminal response mode and nonterminal 
response mode. 
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AS/400 


Application Program SNUF 


i 
Acquire + Allocate session 
| 


2 IMS/VS 


IMS/VS 
Application Program 


| Sendlogon 


«—,— Return code 


Pam oe Post data and end- 


| of-transaction 


Evoke with Invite —_-—> 
| Sendtransaction > Startprogram = =—W—+—_> 
| IDwithdata 
- Reads data and sends 
reply 
| Schedule Read 
Read > < Senddata 


| 
| Schedule Read 


j < 


; returncode 
| Non-terminal response mode 
Evoke with Invite en 
; Sendtransaction > 
ID with data 


Place dataon 
input queue 


Send end of 


—a Return code 


| 

| 

| 

| 

| 

zal 

| 

| 

| 

| 

| 

. | 
transaction | 


Read > 
IMS/VS starts +» Reads data and sends 
program <«—_—______ reply 
«— Endoftransaction 
i withnodata 
Read > 
: | 
«—_ Data andreturn < Sends data | 
i; code 


RSLS163-5 


Figure 5-11. Operating in Terminal and Non-terminal Response Mode 


You describe the terminal response mode with 
one of the following attributes: 


Negated Terminal response mode is not 
used for any transaction. 
Forced Terminal response mode is used 


for every transaction. 


Transaction Terminal response mode is 
defined separately for each trans- 


action. 


Operating in negated terminal response mode 
allows an AS/400 program to evoke several trans- 
actions before receiving a reply from any one of 
them. The program does, however, require more 
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processing because it must correlate replies from 
IMS/VS to the transactions that created them. 


For example, if the program issues an evoke-with- 
invite followed by a read operation, the return 
code indicates no data and end of transaction, or 
it indicates data (a reply) and end of transaction. 
In either case, another transaction can be evoked, 
but the session should not end until all replies 
have been received. After all transactions have 
been evoked, issue input operations until the 
program receives all replies. 


If the program releases the session or ends before 
it receives all replies, data remains on the IMS/VS 
output queue. Data that cannot be recovered that 


is left on the IMS/VS output queue may be lost 
when the program ends a session. Data put on 
the queue after the program releases the session 
becomes the first input record received when 
another AS/400 application program acquires the 
session. 


Operating in forced terminal response mode might 
require less processing than operating in negated 
or transaction mode. This is because IMS/VS 
does not allow input in a session until the system 
sends the reply to the previously evoked trans- 
action. A program that evokes a transaction in a 
session using terminal response mode cannot use 
the same session until it receives the reply. If an 
error prevents the system from sending a reply, 
the session waits for data until the session abnor- 
mally ends. Some conditions that might prevent 
the system from sending a reply message are: 


e LTERM has stopped. 

e IMS/VS is unable to schedule the message 
processing program. 

e A message processing program logic error 
prevents a message from being sent. 


Using Message Format Services 
to Improve Performance 


Message format services can give IMS/VS pro- 
grams independence from terminal requirements 
and can improve online performance. If LTERMS 
are to use message format services, the service 


must be defined during IMS/VS creation. 
Message format services processing begins when 
one of the following occurs: 


¢ The AS/400 program requests message 
format services by sending a function man- 
agement header which contains a message 
identifier (midname). 


¢ The AS/400 program sends // midname before 
sending a message. 


Output messages from IMS/VS that are processed 
by message format services are sent with a func- 
tion management header. To have the AS/400 
program process these headers, specify 
HDPROC(*YES) on the ADDICFDEVE or 
OVRICFDEVE command. 


For a complete description of message format ser- 


vices, see the IMS/VS Message Format Service 
User’s Guide. 


BIND Considerations for AS/400 
Applications Using SNUF 


Refer to SNA Distribution Services, Appendix D, 
for information about using the VM/MVS Bridge. 
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Appendix A. Language Operations, DDS Keywords, and 


System-Supplied Formats 


This appendix contains charts that show the fol- 
lowing for SNUF communications: 


e All valid communications operations supported 
by the intersystem communications function 
(ICF) file. 

e All valid communications operations supported 
and the associated high-level language oper- 
ations. 

¢ Data description specifications (DDS) pro- 
cessing keywords. 

¢ System-supplied formats. 


Intersystem Communications 
Function Operations 


Figure A-1 provides a brief description of the ICF 
operations supported by SNUF. 


Figure A-1. SNUF Supported ICF Operations 


Operation Functional Description 
Open Opens the ICF File. 
Acquire Establishes a session between 


the application and the remote 
location. 


Figure A-1. SNUF Supported ICF Operations 


Operation Functional Description 

Get-attributes Determines the status of the 
session. 

Read Receives data from the remote 
system. 


Receives data from an invited 
program device. 

Sends data records from the 
issuing program to the other 
program in the transaction. 
Allows a write operation fol- 
lowed by a read operation. 
Valid for ILE C/400 and ILE 
RPG/400. 

Attempts to end a session. 
Closes the ICF File. 


Read-from-invited- 
program-devices 
Write 


Write/Read 


Release 
Close 


Language Operations Supported 


Use high-level language operations and ICF to 
communicate with a program at a remote system. 
(See the specific high-level language book for 
operations other than ICF.) Figure A-2 presents 
the ICF file operations used with SNUF commu- 
nications and the equivalent high-level language 
statement. 


Figure A-2 (Page 1 of 2). High-Level Language I/O Operations 


ILE RPG/400 ILE COBOL/400 


ICF Operation Procedure ILE C/400 ILE FORTRAN/400 
Operation Code Statement Function2 Statement 
Open OPEN OPEN fopen, _Ropen OPEN 
Acquire ACQ ACQUIRE QXXACQUIRE, _Racquire Not supported 
Get-attributes POST ACCEPT QXXDEVATR, _Rdevatr Not supported 
Read READ READ fread, _Rreadn READ 
Read-from- invited- program- READ1 READ QXXREADINVDEV fol- Not supported 
devices lowed by an fread, 

_Rreadindv 
Write WRITE WRITE fwrite, _Rwrite WRITE 
Write/Read EXFMT Not supported _Rwriterd Not supported 
Release REL DROP QXXRELEASE, Not supported 

_Rrelease 
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Figure A-2 (Page 2 of 2). High-Level Language I/O Operations 


ILE RPG/400 ILE COBOL/400 


ICF Operation Procedure ILE C/400 ILE FORTRAN/400 
Operation Code Statement Function2 Statement 

Close CLOSE CLOSE fclose, _Rclose CLOSE 

Note: 


1 A read operation can be directed either to a specific program device or to any invited program device. The support provided by 
the compiler you are using determines whether to issue an ICF read or read-from-invited-program-devices operation, based on 
the format of the read operation. For example, if a read is issued with a specific format or terminal specified, the read operation 
is interpreted as an ICF read operation. Refer to the appropriate language reference book for more information. 


2 ILE C/400 programming language is case sensitive. 


DDS Keywords 


Figure A-3 presents the data description specifica- 
tions (DDS) keywords you can use to specify com- 
munications functions for SNUF. For a description 
of how to combine and use DDS keywords, see 
the book, /CF Programming. 


Figure A-3. Valid DDS Keywords for SNUF 


DDS Keyword Function 

ALWWRT Allow-write 

CANCEL Cancel 

CNLINVITE Cancel-invite 

DETACH1 Detach 

ENDGRP End-of-group 

EOS End-of-session 

EVOKE! Evoke 

FAIL Fail 

FMH Function management 
header 

INVITE Invite 

NEGRSP Negative-response 

RCVCANCEL Receive-cancel 

RCVCONFIRM Receive-confirm 

RCVDETACH1 Receive-detach 

RCVENDGRP Receive-end-of-group 

RCVFMH Receive-function man- 
agement header 

RCVNEGRSP Receive-negative- 
response 

RCVTRNRND Receive-turnaround 

RECID Record-identification 

RQSWRT Request-to-write 

RSPCONFIRM Respond-to-confirm 

SECURITY Security 

TIMER Timer 

VARLEN Variable-length data 

Note: 


1 This function is not supported while running in half- 
duplex contention mode. 
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System-Supplied Formats 


You can also use system-supplied communica- 
tions formats to specify communications functions 
in your program. Figure A-4 shows the formats 
you can use with SNUF. For a description of how 
to use system-supplied formats, see the book, /CF 
Programming. 


Figure A-4. Valid System-Supplied Formats for SNUF 


System-Supplied 


Formats Function 

$$CANL Cancel with invite 

$$CANLNI Cancel 

$$CNLINV Cancel-invite 

$$EOS End-of-session 

$$EVOK1 Evoke with invite 

$$EVOKET1 Evoke with detach 

$$EVOKNI1 Evoke 

$$FAIL Fail 

$$NRSP Negative-response with 
invite 

$$NRSPNI Negative-response 

$$POSRSP Positive-response 

$$RCD Request-to-write with 
invite 

$$SEND Send with invite 

$$SENDE Send with end-of-group 

$$SENDET1 Send with detach 

$$SENDFM Send FM Header with 
invite 

$$SENDNF Send FM Header 

$$SENDNI Send 

$$TIMER Timer 

Note: 


1 This format is not supported while running in half- 
duplex contention mode. 


Appendix B. 


Return Codes, Messages, and Sense Codes 


Return Codes 


Major Code 00 
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This section describes all the return codes that are valid for SNUF. These return 
codes are set in the I/O feedback area of the ICF file; they report the results of 
each I/O operation issued by your application program. Your program should 
check the return code and act accordingly. Refer to your high-level language book 
for more information on how to access these return codes. 


Each return code is a four-digit hexadecimal value. The first two digits contain the 
major code, and the last two digits contain the minor code. 


With some return codes, a message is also sent to the job log or the system oper- 
ator message queue (QSYSOPR). You can refer to the message for additional 
information. 


Notes: 


1. In the return code descriptions, your program refers to the local AS/400 appli- 
cation program that issues the operation and receives a return code from ICF 
communications. The remote program refers to the application program on the 
remote system with which your program is communicating through ICF. 

2. Several references to input and output operations are made in the descriptions. 
These operations can include DDS keywords and system-supplied formats, 
which are listed in Appendix A. 


Major Code 00 — Operation completed successfully. 

Description: The operation issued by your program completed successfully. 
Your program may have sent or received some data, or may have received a 
message from the remote system. 


Action: Examine the minor return code and continue with the next operation. 


Code Description/Action 


0000 Description: For input operations issued by your program, 0000 indi- 
cates that your program received some data with a turnaround indi- 
cation. The remote program is ready to receive data. 


For output operations issued by your program, 0000 indicates that the 
last output operation completed successfully and that your program can 
continue to send data. 


Action: If your program received a turnaround on an input operation, 
issue an input or output operation. For the actions which can be taken 
after 0000 is received, refer to the following table: 


B-1 


Figure B-1. Actions for Return Code 0000 

Type of 

Session Last Operation Issued Actions Your Program Can Take 

Started by a Acquire or open Issue an evoke or timer function, or a get- 

source attributes operation. 

program 

Evoke with detach or Issue another evoke function, issue a 

write with detach release operation, continue local pro- 
cessing, or end. 

Any other output oper- Issue another output operation (except 

ation evoke), or issue an input operation. 

End-of-Session Continue local processing or end. 

Started by a Acquire or open Issue an input or output operation. 

remote 

program start 

request! 

Write with detach Continue local processing or end. This 
session has ended. 

Any other output oper- Issue another output operation (except 

ation evoke), or issue an input operation. 

End-of-Session Continue local processing or end. 

1 A target program (started by a program start request) cannot issue an evoke function 
in this session; it can issue an evoke function only in a different session that it has first 
acquired. 

0001 Description: On a successful input operation, your program received 


some data. Your program must continue to receive data until it 
receives a turnaround indication (which allows your program to send 
data) or a detach indication. 


Action: Issue another input operation. If your program detects a turn- 
around indication, it can issue an output operation. 


0003 Description: On a successful input operation, your program received 
some data with an end-of-group indication. Your program may also 
have received a definite-response-request with the end-of-group indi- 
cation. 


Action: Issue an input operation to receive the next group of records. 
You may also issue a $$POSRSP format to respond to the definite- 
response-request. If you are using DDS keywords, you can use the 
RCVCONFIRM and RSPCONFIRM keywords. If your program receives 
a definite-response-request and you ignore it, SNUF sends a positive 
response to the application when the next input/output operation is per- 
formed. 


0004 Description: On a successful input operation, your program received 
some data with a function-management-header (FMH) and a turn- 
around indication. The remote program is ready to receive data. 


Action: Issue a second input operation to receive the FMH data, then 
issue an output operation. 
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0005 


0007 


0008 


000C 


0010 


0020 


0021 


Description: On a successful input operation, your program received 
some data with a function-management-header (FMH). 


Action: Your program can issue a second input operation to receive 
the FMH data, then issue another input operation to continue receiving 
data until it receives a turnaround indication or a detach indication. 


Description: On a successful input operation, your program received 
a function-management-header (FMH) and an end-of-group indication. 
Your program should continue to receive data. 


Action: Issue a second input operation to receive the FMH data, then 
issue another input operation to receive the next group of records. 


Description: On a successful input operation, your program received 
a detach indication with the last of the data. The communications 
transaction with the remote program has ended, but the session with 
the remote system is still active. 


Action: If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 


Description: On a successful input operation, your program received 
the last of the data with a function-management-header (FMH) and a 
detach indication. The communications transaction with the remote 
program has ended, but the session with the remote system is still 
active. 


Action: Issue a second input operation to receive the data. If your 
program started the transaction, issue another evoke function (to start 
another program), issue a release operation (to perform local pro- 
cessing or to start another session), or end your program. If a program 
start request from the remote program started the transaction, issue an 
end-of-session function or end your program. 


Description: On a successful output operation, your program received 
a request-to-turnaround indication. The remote program wants to send 
data as soon as possible. You should allow the remote program to 
send this data. 


Action: Issue an input operation as soon as possible. 


Description: On a successful input operation, your program received 

a remote system message and a turnaround indication. The message 

is in your program's input buffer and describes why the previous opera- 
tion was rejected. 


Action: Handle the message in the input buffer (for example, display 
it). Your program now has control of the session, and can issue an 
output operation. 


Description: On a successful input operation, your program received 
a remote system message which is now in your program's input buffer. 
Your program should continue to receive input. 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 
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0023 


0025 


0027 


0028 


0030 


0031 


0033 


Description: On a successful input operation, your program received 
a remote system message with an end-of-group indication. The system 
message is now in your input buffer. 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 


Description: On a successful input operation, your program received 
a remote system message with a function-management-header (FMH). 


Action: Process the FMH and issue a second input operation to 
receive the system message. 


Description: On a successful input operation, your program received 
a remote system message with a function-management-header (FMH) 
and an end-of-group indication. 


Action: Process the FMH and issue a second input operation to 
receive the system message. 


Description: On a successful input operation, your program received 
a detach indication with a remote system message. The communica- 
tions transaction with the remote program has ended, but the session 
with the remote system is still active. The system message is in your 
program's input buffer and describes the status of the transaction that 
has ended. 


Action: Handle the message in the input buffer (for example, display 
it). If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 


Description: On a successful input operation, your program received 
a truncated remote system message and a turnaround indication. The 
message is in your program's input buffer, and was truncated because 
it was too long for the buffer. The message describes why the previous 
operation was rejected. 


Action: Handle the message in the input buffer (for example, display 
it). Your program now has control of the session, and can issue an 
output operation. 


Description: On a successful input operation, your program received 
a truncated remote system message. The message is in your pro- 
gram's input buffer, and was truncated because it was too long for the 
buffer. Your program should continue to receive input. 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 


Description: On a successful input operation, your program received 
a truncated system message with an end-of-group indication. The 
message is in your input buffer, and was truncated because it was too 
long for the buffer. 
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0035 


0037 


0038 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 


Description: On a successful input operation, your program received 
a truncated system message with a function-management-header 
(FMH). The message is in your input buffer, and was truncated 
because it was too long for the buffer. 


Action: Process the FMH and issue a second input operation to 
receive the system message. 


Description: On a successful input operation, your program received 
a truncated system message with a function-management-header 
(FMH) and an end-of-group indication. 


Action: Process the FMH and issue a second input operation to 
receive the system message. 


Description: On a successful input operation, your program received 
a detach indication with a truncated remote system message. The 
communications transaction with the remote program has ended, but 
the session with the remote system is still active. The message is in 
your program's input buffer and describes the status of the transaction 
that has ended. The message was truncated because it was too long 
for the buffer. 


Action: Handle the message in the input buffer (for example, display 
it). If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 
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Major Code 02 


Major Code 02 — Input operation completed successfully, but your job is being 
ended (controlled). 


Description: The input operation issued by your program completed success- 
fully. Your program may have received some data or a message from the 
remote system. However, your job is being ended (controlled). 


Action: Your program should complete its processing and end as soon as pos- 
sible. The system eventually changes a job ended (controlled) to a job ended 
(immediate) and forces all processing to stop for your job. 


Code 
0200 


0201 


0203 


0204 


Description/Action 


Description: On a successful input operation, your program received 
some data with a turnaround indication. Also, your job is being ended 
(controlled). The remote program is ready to receive data from your 
program. 


Action: Your program can issue an input or output operation. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


Description: On a successful input operation, your program received 
some data. Also, your job is being ended (controlled). Your program 
can continue to receive data until it receives a turnaround indication 
(which allows your program to send data) or a detach indication. 


Action: Your program can issue another input operation. If your 
program detects the equivalent of a turnaround indication, it can issue 
an output operation. However, the recommended action is to complete 
all processing and end your program as soon as possible. The system 
eventually changes a job ended (controlled) to a job ended (immediate) 
and forces all processing to stop for your job. 


Description: On a successful input operation, your program received 
some data with an end-of-group indication. Also, your job is being 
ended (controlled). 


Action: Your program can issue an input operation to receive the next 
group of records. However, the recommended action is to complete all 
processing and end your program as soon as possible. The system 
eventually changes a job ended (controlled) to a job ended (immediate) 
and forces all processing to stop for your job. 


Description: On a successful input operation, your program received 
some data with a function-management-header (FMH) and a turn- 
around indication. Also, your job is being ended (controlled). The 
remote program is ready to receive data. 


Action: Your program can issue a second input operation to receive 
the FMH data, then issue an output operation. However, the recom- 
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0205 


0207 


0208 


020C 


mended action is to complete all processing and end your program as 
soon as possible. The system eventually changes a job ended (con- 
trolled) to a job ended (immediate) and forces all processing to stop for 
your job. 


Description: On a successful input operation, your program received 
some data with a function-management-header (FMH). Also, your job 
is being ended (controlled). 


Action: Your program can issue a second input operation to receive 
the FMH data, then issue another input operation to continue receiving 
data until it receives a turnaround indication or a detach indication. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


Description: On a successful input operation, your program received 
a function-management-header (FMH) and an end-of-group indication. 
Also, your job is being ended (controlled). 


Action: Your program can issue a second input operation to receive 
the FMH data, then issue another input operation to receive the next 
group of records. However, the recommended action is to complete all 
processing and end your program as soon as possible. The system 
eventually changes a job ended (controlled) to a job ended (immediate) 
and forces all processing to stop for your job. 


Description: On a successful input operation, your program received 
a detach indication with the last of the data. The communications 
transaction with the remote program has ended, but the session with 
the remote system is still active. Also, your job is being ended (con- 
trolled). 


Action: If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


Description: On a successful input operation, your program received 
the last of the data with a function-management-header (FMH) and a 
detach indication. The communications transaction with the remote 
program has ended, but the session with the remote system is still 
active. Also, your job is being ended (controlled). 


Action: Issue a second input operation to receive the data. If your 
program started the transaction, issue another evoke function (to start 
another program), issue a release operation (to perform local pro- 
cessing or to start another session), or end your program. If a program 
start request from the remote program started the transaction, issue an 
end-of-session function or end your program. However, the recom- 
mended action is to complete all processing and end your program as 
soon as possible. The system eventually changes a job ended (con- 
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trolled) to a job ended (immediate) and forces all processing to stop for 
your job. 


0220 Description: On a successful input operation, your program received 
a remote system message and a turnaround indication. The message 
is in your program's input buffer and describes why the previous opera- 
tion was rejected. Also, your job is being ended (controlled). 


Action: Handle the message in the input buffer (for example, display 
it). Your program now has control of the session, and can issue an 
output operation. However, the recommended action is to complete all 
processing and end your program as soon as possible. The system 
eventually changes a job ended (controlled) to a job ended (immediate) 
and forces all processing to stop for your job. 


0221 Description: On a successful input operation, your program received 
a remote system message which is now in your program's input buffer. 
Also, your job is being ended (controlled). Your program should con- 
tinue to receive input. 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


0223 Description: On a successful input operation, your program received 
a remote system message with an end-of-group indication. The system 
message is now in your input buffer. Also, your job is being ended 
(controlled). 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


0225 Description: On a successful input operation, your program received 
a remote system message with a function-management-header (FMH). 
Also, your job is being ended (controlled). 


Action: Process the FMH and issue a second input operation to 
receive the system message. However, the recommended action is to 
complete all processing and end your program as soon as possible. 
The system eventually changes a job ended (controlled) to a job ended 
(immediate) and forces all processing to stop for your job. 


0227 Description: On a successful input operation, your program received 
a remote system message with a function-management-header (FMH) 
and an end-of-group indication. Also, your job is being ended (con- 
trolled). 


Action: Process the FMH and issue a second input operation to 
receive the system message. However, the recommended action is to 
complete all processing and end your program as soon as possible. 
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0228 


0230 


0231 


0233 


The system eventually changes a job ended (controlled) to a job ended 
(immediate) and forces all processing to stop for your job. 


Description: On a successful input operation, your program received 
a detach indication with a remote system message. The communica- 
tions transaction with the remote program has ended, but the session 
with the remote system is still active. The system message is in your 
program's input buffer and describes the status of the transaction that 
has ended. Also, your job is being ended (controlled). 


Action: Handle the message in the input buffer (for example, display 
it). If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


Description: On a successful input operation, your program received 
a truncated remote system message and a turnaround indication. The 
message is in your program's input buffer, and was truncated because 
it was too long for the buffer. The message describes why the previous 
operation was rejected. Also, your job is being ended (controlled). 


Action: Handle the message in the input buffer (for example, display 
it). Your program now has control of the session, and can issue an 
output operation. However, the recommended action is to complete all 
processing and end your program as soon as possible. The system 
eventually changes a job ended (controlled) to a job ended (immediate) 
and forces all processing to stop for your job. 


Description: On a successful input operation, your program received 
a truncated remote system message. The message is in your pro- 
gram's input buffer, and was truncated because it was too long for the 
buffer. Also, your job is being ended (controlled). Your program 
should continue to receive input. 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


Description: On a successful input operation, your program received 
a truncated system message with an end-of-group indication. The 
message is in your input buffer, and was truncated because it was too 
long for the buffer. Also, your job is being ended (controlled). 


Action: Handle the message in the input buffer (for example, display 
it), and issue another input operation. If your program detects the 
equivalent of a turnaround indication, it can issue an output operation. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
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changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 


0235 Description: On a successful input operation, your program received 
a truncated system message with a function-management-header 
(FMH). The message is in your input buffer, and was truncated 
because it was too long for the buffer. Also, your job is being ended 
(controlled). 


Action: Process the FMH and issue a second input operation to 
receive the system message. However, the recommended action is to 
complete all processing and end your program as soon as possible. 
The system eventually changes a job ended (controlled) to a job ended 
(immediate) and forces all processing to stop for your job. 


0237 Description: On a successful input operation, your program received 
a truncated system message with a function-management-header 
(FMH) and an end-of-group indication. Also, your job is being ended 
(controlled). 


Action: Process the FMH and issue a second input operation to 
receive the system message. However, the recommended action is to 
complete all processing and end your program as soon as possible. 
The system eventually changes a job ended (controlled) to a job ended 
(immediate) and forces all processing to stop for your job. 


0238 Description: On a successful input operation, your program received 
a detach indication with a truncated remote system message. The 
communications transaction with the remote program has ended, but 
the session with the remote system is still active. The message is in 
your program's input buffer and describes the status of the transaction 
that has ended. The message was truncated because it was too long 
for the buffer. Also, your job is being ended (controlled). 


Action: Handle the message in the input buffer (for example, display 
it). If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 
However, the recommended action is to complete all processing and 
end your program as soon as possible. The system eventually 
changes a job ended (controlled) to a job ended (immediate) and forces 
all processing to stop for your job. 
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Major Code 03 


Major Code 03 — Input operation completed successfully, but no data received. 


Description: The input operation issued by your program completed success- 
fully, but no data was received. 


Action: Examine the minor return code and continue with the next operation. 


Code 
0300 


0301 


0303 


0308 


0309 


0310 


Description/Action 


Description: On a successful input operation, your program received 
a turnaround indication without any data. The session is still active. 


Action: Issue an input or output operation. 


Description: On a successful input operation, your program received 
no data. Your program must continue to receive input until it receives a 
turnaround or detach indication. 


Action: Issue an input operation. 


Description: On a successful input operation, your program received 
an end-of-group indication without any data. 


Action: Issue another input operation. 


Description: On a successful input operation, your program received 
a detach indication without any data. The communications transaction 
with the remote program has ended, but the session with the remote 
system is still active. If you specified the DDS keyword RCVDETACH, 
the receive-detach indicator is also set on. 


Action: If your program started the session, it can issue another evoke 
function (to start another program), issue a release operation (to 
perform local processing or to start another session), or end. Ifa 
program start request from the remote program started the transaction, 
your program can either issue an end-of-session function or end. 


Description: On a read-from-invited-program-devices operation, your 
program did not receive any data. Also, your job is being ended (con- 
trolled). 


Action: Your program can continue processing. However, the recom- 
mended action is to complete all processing and end your program as 
soon as possible. The system eventually changes a job ended (con- 
trolled) to a job ended (immediate) and forces all processing to stop for 
your job. 


Messages: 
CPF4741 (Notify) 


Description: On a read-from-invited-program-devices operation, the 
time interval specified by a timer function in your program or by the 
WAITRCD value specified for the ICF file expired. 


Action: Issue the intended operation after the specified time interval 
has ended. For example, if you were using the time interval to control 
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the length of time to wait for data, you can issue another read-from- 
invited-program-devices operation to receive the data. 


Note: Since no specific program device name is associated with the 
completion of this operation, the program device name in the 
common I/O feedback area is set to *N. Therefore, your 
program should not make any checks based on the program 
device name after receiving the 0310 return code. 


Messages: 


CPF4742 (Status) 
CPF4743 (Status) 


Major Code 04 


Major Code 04 — Output exception occurred. 

Description: An output exception occurred because your program attempted to 
send data when it should be receiving data. The data from your output opera- 
tion was not sent. You can attempt to send the data later. 


Action: Issue an input operation to receive the data. 


Code Description/Action 


0412 Description: An output exception occurred because your program 
attempted to send data when it should be receiving data that was sent 
by the remote program. The data from your output operation was not 
sent to the remote system. Your program can attempt to send the data 
later. 


Action: Issue an input operation to receive the data. 


Note: If your program issues another output operation before an input 
operation, your program receives a return code of 831C. 


Messages: 


CPF4750 (Notify) 
CPF5076 (Notify) 
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Major Codes 08 and 11 


Major Codes 08 and 11 — Miscellaneous program errors occurred. 
Description: The operation just attempted by your program was not suc- 
cessful. The operation may have failed because it was issued at the wrong 
time. 


Action: Refer to the minor code description for the appropriate recovery action. 


Code Description/Action 


0800 Description: The acquire operation just attempted by your program 
was not successful. Your program tried to acquire a program device 
that was already acquired and is still active. 


Action: If the session associated with the original acquire operation is 
the one needed, your program can begin communicating in that session 
since it is already available. If you want a different session, issue 
another acquire operation for the new session by specifying a different 
program device name in the PGMDEV parameter of the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command that precedes the program. 


Messages: 


CPD4077 (Diagnostic) 
CPF5041 (Status) 
CPF50A0 (Status) 


1100 Description: The read-from-invited-program-devices operation just 
attempted by your program was not successful because your program 
tried this operation when no program devices were invited and no timer 
function was in effect. 


Action: Issue an invite function (or a combined operation that includes 
an invite) followed by a read-from-invited-program-devices operation. 


Messages: 
CPF4740 (Notify) 
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Major Code 34 


Major Code 34 — Input exception occurred. 

Description: The input operation attempted by your program was not suc- 
cessful. The data received was too long for your program's input buffer or was 
not compatible with the record format specified on the input operation. 


Action: Refer to the minor code description for the appropriate recovery action. 


Code 
3401 


3441 


3451 


Description/Action 


Description: The input operation issued by your program was not suc- 
cessful because the length of the data record sent by the remote 
system was longer than the length specified for your program's input 
buffer. The length of the data record received from the remote system, 
if available, is in the actual-record-length field in the I/O feedback area. 


Action: Issue another input operation if your program can specify a 
record size large enough to receive the data, plus any indicators for a 
file without a separate indicator area. Otherwise, you should close the 
file, end your program, correct the record size, then run your program 
again. 


Messages: 
CPF4768 (Notify) 


Description: A valid record format name was specified with format 
selection type *RECID. However, although the data received matched 
one of the record formats in the ICF file, it did not match the format 
specified on the read operation. 


Action: Correct your program to issue a read operation that does not 
specify a record format name, or specify the correct record format 
name to process the data based on the format selection option for the 
file. 


Messages: 
CPF5058 (Notify) 


Description: Your program specified a file record size that was not 
large enough for the indicators to be included with the data sent by the 
remote program (for a file defined with a nonseparate indicator area). 
Your program did not receive any data. For a file using a nonseparate 
indicator area, the actual record length field in the device-dependent I/O 
feedback area contains the number of indicators specified by the record 
format. 


Action: End the session; close the file; correct the file record size; 
then open the file again. 


Messages: 
CPF4768 (Notify) 
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Major Code 80 


Major Code 80 — Permanent system or file error (irrecoverable). 


Description: An irrecoverable file or system error has occurred. The under- 
lying communications support may have ended and your session has ended. If 
the underlying communications support ended, it must be established again 
before communications can resume. Recovery from this error is unlikely until 
the problem causing the error is detected and corrected. 


Action: You can perform the following general actions for all 80xx return 
codes. Specific actions are given in each minor code description. 


¢ Close the file, open the file again, then establish the session. If the opera- 
tion is still not successful, your program should end the session. 

¢ Continue local processing. 

e End. 


Note: If the session is started again, it starts from the beginning, not at the 
point where the session error occurred. 


Code Description/Action 


8081 Description: The operation attempted by your program was not suc- 
cessful because a system error condition was detected. 


Action: Your communications configurations may need to be varied off 
and then on again. Your program can do one of the following: 


¢ Continue local processing. 

e Close the ICF file, open the file again, and establish the session 
again. 

e End. 


Messages: 


CPF4170 (Escape) 
CPF4510 (Escape) 
CPF5089 (Escape) 
CPF5257 (Escape) 
CPF5411 (Escape) 


8082 Description: The operation attempted by your program was not suc- 
cessful because the device supporting communications between your 
program and the remote location is not usable. For example, this may 
have occurred because communications were stopped for the device by 
a Hold Communications Device (HLDCMNDEV) command. Your 
program should not issue any operations to the device. 


Action: Communications with the remote program cannot resume until 
the device has been reset to a varied on state. If the device has been 
held, use the Release Communications Device (RLSCMNDEV) 
command to reset the device. If the device is in an error state, vary the 
device off and then on again. Your program can attempt to establish 
the session again, continue local processing, or end. 
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Messages: 


CPF4744 (Escape) 
CPF5269 (Escape) 


80B3 Description: The open operation issued by your program was not suc- 
cessful because the ICF file is in use by another process. 


Action: Wait for the file to become available, then issue another open 
operation. Otherwise, your program may continue processing, or it can 
end. 


Consider increasing the WAITFILE parameter with the Change ICF File 
(CHGICFF) or Override ICF File (OVRICFF) command to allow more 
time for the file resources to become available. 


Messages: 
CPF4128 (Escape) 


80EB Description: The open operation attempted by your program was not 
successful due to one of the following: 


e¢ Your program used an option of update or delete to open the file, 
but that option is not supported by the program device. 

e Your program requested both blocked data and user buffers on an 
open option, but these formats cannot be selected together. 

¢ Your program tried to open a source file, but the file was not 
created as a source file. 

e There is a mismatch on the INDARA keyword between your 
program and the ICF file as to whether or not a separate indicator 
area should be used. 

e The file was originally opened as a shared file; however, no 
program devices were ever acquired for the file before your 
program attempted the current open operation. 


Action: After performing one of the following actions, your program 
can try the open operation again: 


e If the update and delete options are not supported for the program 
device, use an option of input, output, or both. 

e lf your program tried selecting user buffers and blocked data 
together, it should try selecting one or the other, but not both. 

e lf your program tried to open a non-source file as a source file, 
either change the file name or change the library name. 

e If there was a mismatch on the INDARA keyword, either correct the 
file or correct your program so that the two match. 

e If no program devices were previously acquired for a shared file, 
acquire one or more program devices for the file. 


Messages: 


CPF4133 (Escape) 
CPF4156 (Escape) 
CPF4238 (Escape) 
CPF4250 (Escape) 
CPF4345 (Escape) 
CPF5522 (Escape) 
CPF5549 (Escape) 
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80ED 


80EF 


80F8 


Description: The open operation attempted by your program was not 
successful because there is a record format level mismatch between 
your program and the ICF file. 


Action: Close the file. Compile your program again to match the file 
level of the ICF file, or change or override the file to LVLCHK(*NO); 
then open the file again. 


Messages: 
CPF4131 (Escape) 


Description: Your program attempted an open operation on a file or 
library for which the user is not authorized. 


Action: Close the file. Either change the file or library name on the 
open operation, or obtain authority for the file or library from your secu- 
rity officer. Then issue the open operation again. 


Messages: 
CPF4104 (Escape) 


Description: The open operation attempted by your program was not 
successful because one of the following occurred: 


e The file is already open. 
e The file is marked in error on a previous return code. 


Action: 


e If the file is already open, close the file and end your program. 
Remove the duplicate open operation from your program, then 
issue the open operation again. 

e If the file is marked in error, your program can check the job log to 
see what errors occurred previously, then take the appropriate 
recovery action for those errors. 


Messages: 


CPF4132 (Escape) 
CPF5129 (Escape) 
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Major Code 81 


Major Code 81 — Permanent session error (irrecoverable). 


Description: An irrecoverable session error occurred during an I/O operation. 
Your session cannot continue and has ended. Before communications can 
resume, the session must be established again by using an acquire operation or 
another program start request. Recovery from this error is unlikely until the 
problem causing the error is detected and corrected. Operations directed to 
other sessions associated with the file should work. 


Action: You can perform the following general actions for all 81xx return 
codes. Specific actions are given in each minor return code description. 


If your program initiated the session, you can: 


¢ Correct the problem and establish the session again. If the operation is still 
not successful, your program should end the session. 

¢ Continue processing without the session. 

e End. 


If your session was initiated by a program start request from the remote 
program, you can: 


¢ Continue processing without the session. 
e End. 


Several of the minor codes indicate that an error condition must be corrected by 
changing a value in the communications configuration or in the file. 


¢ To change a parameter value in the communications configuration, vary the 
configuration off, make the change to the configuration description, then 
vary the configuration on. 

¢ To change a parameter value in the file, use the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command. 


Note: When a parameter can be specified both in the ADDICFDEVE or 
OVRICFDEVE command and in the configuration, the value in the 
ADDICFDEVE or OVRICFDEVE command overrides the value spec- 
ified in the configuration (for your program only). Therefore, in some 
cases, you may choose to make a change with the ADDICFDEVE or 
OVRICFDEVE command rather than in the configuration. 


Several other minor codes indicate a line or remote system error and may 
require an operator to correct the error. 


Note: If the session is started again, it starts from the beginning, not at the 
point where the session error occurred. 
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Code 
8140 


8191 


8196 


819D 


81B9 


Description/Action 


Description: A cancel reply was received from your program or from 
the operator in response to a notify message, or was the result of a 
system default, causing the session to be ended. The session is no 
longer active. 


Action: If your program started the session, issue an acquire opera- 
tion to start the session again. If your program was started by a 
program start request, it can continue local processing or end. 


Messages: 
CPF5104 (Escape) 


Description: A permanent line or controller error occurred on an input 
or output operation, and the system operator attempted recovery in 
response to the error message. You can learn what type of line error 
occurred by checking the system operator's message queue. The 
session has ended. Data may have been lost. 


Action: If your program started the session, issue an acquire opera- 
tion to start the session again. If your program was started by a 
program start request from the remote program, it can continue local 
processing or end. 


Messages: 


CPF4146 (Escape) 
CPF4542 (Escape) 
CPF5128 (Escape) 


Description: The remote system sent a Systems Network Architecture 
(SNA) UNBIND command to your system, or the session was ended 
locally. 


Action: To start another session, issue the acquire operation again. 
Otherwise, your program can continue local processing or end. 


Messages: 
CPF5165 (Escape) 


Description: On an input or output operation, your program received 
some unexpected data from the remote program. The session has 
ended. 


Action: Your program is expecting the remote program to send a 
detach indication with no data. 


Messages: 
CPF5089 (Escape) 


Description: On an input operation, the remote program sent a data 
record whose length was greater than the maximum user record length 
specified for your session. The session has ended. 


Action: Verify that the value in the user record length (RCDLEN) 
parameter on the device description (CRTDEVSNUF) command or on 
the ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE command is large 
enough for the longest record to be received. 


Messages: 
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CPF5305 (Escape) 
CPF5335 (Escape) 
CPF5388 (Escape) 


81E9 Description: An input operation was issued and the format selection 
option for the ICF file was *RECID, but the data received did not match 
any record formats in the file. There was no format in the file defined 
without a RECID keyword, so there was no default record format to 
use. The session has ended. 


Action: Verify that the data sent by the remote program was correct. 
If the data was not correct, have the operator on the remote system 
change the remote program to send the correct data. If the data was 
correct, add a RECID keyword definition to the file that matches the 
data, or define a record format in the file without a RECID keyword so 
that a default record format can be used on input operations. If your 
program started the session, use another acquire operation to start the 
session again. If a program start request started your program, con- 
tinue local processing or end. 


Messages: 
CPF5291 (Escape) 
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Major Code 82 


Major Code 82 — Open or acquire operation failed. 


Description: Your attempt to establish a session was not successful. The 
error may be recoverable or permanent, and recovery from it is unlikely until the 
problem causing the error is detected and corrected. 


Action: You can perform the following general actions for all 82xx return 
codes. Specific actions are given in each minor code description. 


If your program was attempting to start the session, you can: 


¢ Correct the problem and attempt to establish the session again. The next 
operation could be successful only if the error occurred because of some 
temporary condition such as the communications line being in use at the 
time. If the operation is still not successful, your program should end. 

¢ Continue processing without the session. 

e End. 


If your session was initiated by a program start request from the remote 
program, you can: 


¢ Correct the problem and attempt to connect to the requesting program 
device again. If the operation is still not successful, your program should 
end. 

¢ Continue processing without the session. 

e End. 


Several of the minor codes indicate that an error condition must be corrected by 
changing a value in the communications configuration or in the file. 


¢ To change a parameter value in the communications configuration, vary the 
configuration off, make the change to the configuration description, then 
vary the configuration on. 

¢ To change a parameter value in the file, use the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command. 


Note: When a parameter can be specified both in the ADDICFDEVE or 
OVRICFDEVE command and in the configuration, the value in the 
ADDICFDEVE or OVRICFDEVE command overrides the value spec- 
ified in the configuration (for your program only). Therefore, in some 
cases, you may choose to make a change with the ADDICFDEVE or 
OVRICFDEVE command rather than in the configuration. 


If no changes are needed in your file or in the configuration (and depending on 
what the return code description says): 


e If the attempted operation was an acquire, issue the acquire operation 
again. 

e lf the attempted operation was an open, close the file and issue the open 
operation again. 
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Code Description/Action 


8209 Description: The open or acquire operation issued by your program 
was not successful because a prestart job is being canceled. One of 
the following may have occurred: 


e An End Job (ENDJOB), End Prestart Job (ENDPJ), End Subsystem 
(ENDSBS), End System (ENDSYS), or Power Down System 
(PWRDWNSYS) command was being issued. 

¢ The maximum number of prestart jobs (MAXJOBS parameter) was 
reduced by the Change Prestart Job Entry (CHGPJE) command. 

e The value for the maximum number of program start requests 
allowed (specified in the MAXUSE parameter on the ADDPJE or 
CHGPJE command) was exceeded. 

e Too many unused prestart jobs exist. 

e The prestart job had an initialization error. 


Action: Complete all processing and end your program as soon as 
possible. Correct the system error before starting this job again. 


Messages: 


CPF4292 (Escape) 
CPF5313 (Escape) 


8233 Description: A program device name that was not valid was detected. 
Either an ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE command 
was not run, or the program device name in your program does not 
match the program device name specified in the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command for the session being 
acquired. The session was not started. 


Action: If the error was in your program, change your program to 
specify the correct program device name. If an incorrect identifier was 
specified in the ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE 
command, specify the correct value in the PGMDEV parameter. 


Messages: 


CPF4288 (Escape) 
CPF5068 (Escape) 


8281 Description: On an unsuccessful open or acquire operation, a system 
error condition was detected. For example, the file may previously 
have been in error, or the file could not be opened due to a system 
error. 


Action: Your communications configurations may need to be varied off 
and then on again. Your program can do one of the following: 


¢ Continue local processing. 

¢ Close the ICF file, open the file again, and acquire the program 
device again. However, if this results in another 8281 return code, 
your program should close the file and end. 

¢ Close the file and end. 


Messages: 


CPF4121 (Escape) 
CPF4168 (Escape) 
CPF4182 (Escape) 
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8282 


8285 


8291 


CPF4369 (Escape) 
CPF4370 (Escape) 
CPF4375 (Escape) 
CPF5257 (Escape) 
CPF5274 (Escape) 
CPF5317 (Escape) 
CPF5318 (Escape) 


Description: The open or acquire operation attempted by your 
program was not successful because the device supporting commu- 
nications between your program and the remote location is not usable. 
For example, this may have occurred because communications were 
stopped for the device by a Hold Communications Device 
(HLDCMNDEV) command. Your program should not issue any oper- 
ations to the device. The session was not started. 


Action: Communications with the remote program cannot resume until 
the device has been reset to a varied on state. If the device has been 
held, use the Release Communications Device (RLSCMNDEV) 
command to reset the device. If the device is in an error state, vary the 
device off, then on again. Your program can attempt to acquire the 
program device again, continue local processing, or end. 


Messages: 


CPF4298 (Escape) 
CPF5269 (Escape) 


Description: On an open or acquire operation, the attempt by your 
program to call a remote location automatically using a switched con- 
nection was not successful. The number specified on the controller 
description was dialed, but the connection was not established. Pos- 
sible causes are that the line was busy, that there was no answer, or 
that the number dialed was disconnected. The session was not 
started. 


Action: Verify that the number you are dialing is correct and that the 
remote system is ready for the call. Also verify that the line description 
you are using is varied on and is included in the switched line list on 
the controller description. Your program can issue the open or acquire 
operation again, continue local processing, or end. 


Messages: 


CPF4179 (Escape) 
CPF5260 (Escape) 


Description: A permanent line or controller error occurred on an 
unsuccessful open or acquire operation, and the system operator took 
a recovery option in response to the error message. The session was 
not started. 


Action: If your program was attempting to start the session, it can try 
the acquire operation again. If your program was started by a program 
start request from the remote program, your program can continue local 
processing or end. 


Messages: 
CPF4146 (Escape) 
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CPF5353 (Escape) 


82A1 Description: The acquire operation issued by your program was not 
successful because the logon portion of the acquire operation failed. 
The host subsystem may have been inactive, or the name of the 
remote application program specified in the application ID (APPID) 
parameter on the ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE 
command may have been incorrect. The session was not started. 


Action: Verify that the name of the remote application program is 
specified correctly on the ADDICFDEVE, CHGICFDEVE, or 
OVRICFDEVE command. If the program name is specified correctly, 
contact the remote location and request that the host system be 
started, then issue the acquire operation again. Otherwise, your 
program can continue local processing, wait to send the acquire opera- 
tion again, or end. 


Messages: 


CPF4180 (Escape 
CPF4226 (Escape 
CPF4758 (Escape 
CPF5228 (Escape 
CPF5516 (Escape 
CPF5518 (Escape 
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82A5 Description: On an unsuccessful acquire operation, SNUF detected a 
combination of parameter values on the ADDICFDEVE, CHGICFDEVE, 
or OVRICFDEVE command that was not valid. The session was not 
started. 


Action: Change the parameter values on the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command, then issue the acquire 
operation again. 


Messages: 


CPF4303 (Escape) 
CPF5511 (Escape) 
CPF5338 (Escape) 


82A6 Description: On the open or acquire operation attempted by your 
program, a negative-response with sense data was received when the 
Systems Network Architecture (SNA) BIND command was sent to the 
user to start the session. The session was not started. 


Action: Close the file. Check for an error in the format of the incorrect 
BIND command, or contact the remote system to determine why the 
command failed. After correcting the error, your program can issue the 
acquire operation again to start the session. 


Messages: 


CPF4227 (Escape) 
CPF4333 (Escape) 
CPF4527 (Escape) 
CPF5517 (Escape) 
CPF5538 (Escape) 
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82A7 


82A8 


82A9 


Description: The open or acquire operation attempted by your 
program was not successful because the specified program device was 
already in use. The session was not started. 


Action: Your program can wait for the program device to become 
available, then try the open or acquire operation again. Otherwise, it 
can continue local processing or end. 


Messages: 


CPF4106 (Escape) 
CPF5507 (Escape) 


Description: The acquire operation attempted by your program was 
not successful because the maximum number of program devices 
allowed for the ICF file has been reached. The session was not 
started. 


Action: Your program can recover by releasing a different program 
device and issuing the acquire operation again. If more program 
devices are needed, close the file and increase the MAXPGMDEV 
value for the ICF file. 


Messages: 


CPF4745 (Diagnostic) 
CPF5041 (Status) 


Description: The acquire operation issued by your program to a 
“REQUESTER device was not successful due to one of the following 
causes: 


e Your program has already acquired the *REQUESTER device. 

e The job was started by a program start request with the 
“REQUESTER device detached. 

e The *REQUESTER device was released because an end-of- 
session was requested. 

e The job does not have a *REQUESTER device; that is, the job was 
not started by a program start request. 

¢ A permanent error occurred on the session. 


Action: 


e If the *REQUESTER device is already acquired and your program 
expects to communicate with the *REQUESTER device, use the 
program device that acquired the *REQUESTER. 

e If the *REQUESTER device is not available and your program 
expects to communicate with the “~REQUESTER device, the remote 
program must send a program start request without a detach func- 
tion. 

e lf your program released its *REQUESTER device, before trying to 
acquire it, correct the error that caused your program 

e lf this job does not have a *REQUESTER device, correct the error 
that caused your program to attempt to acquire a “~REQUESTER 
device. 

e lf a permanent error caused the acquire operation to fail, verify that 
your program correctly handles the permanent error return codes 
(80xx, 81xx) it received on previously issued input and output oper- 
ations. Because your program was started by a program start 
request, your program cannot attempt error recovery after receiving 
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a permanent error return code. It is the responsibility of the remote 
program to initiate error recovery. 


Messages: 


CPF4366 (Escape) 
CPF5380 (Escape) 
CPF5381 (Escape) 


82AA Description: The open or acquire operation attempted by your 
program was not successful because the remote location name speci- 
fied on the ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE command 
does not match any remote location configured on the system. The 
session was not started. 


Action: Your program can continue local processing, or close the file 
and end. Verify that the name of the remote location is specified cor- 
rectly in the RMTLOCNAME parameter on the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command. 


Messages: 


CPF4103 (Escape) 

CPF4363 (Escape) 

CPF4364 (Escape) 

CPF4747 (Escape) 

CPF5378 (Escape) 

CPF5379 (Escape) 

82AB Description: The open or acquire operation attempted by your 
program was not successful because the device description for the 
remote location was not varied on. The session was not started. 


Action: Your program can wait until the communications configuration 
is varied on and then issue the acquire operation again, it can try the 
acquire operation again using a different device description, continue 
local processing, or end. 


Messages: 


CPF4285 (Escape) 
CPF5333 (Escape) 


82B3 Description: The open or acquire operation attempted by your 
program was not successful because your program is trying to use a 
device description that is already in use by another job. The session 
was not started. 


Action: Wait for the device description to become available, then issue 
the acquire operation again. You can use the Work with Configuration 
Status (WRKCFGSTS) command to determine which job is using the 
device description. Consider increasing the WAITFILE parameter of 
the CHGICFF or OVRICFF command to allow more time for the device 
to become available. Otherwise, your program can continue local pro- 
cessing or end. 


Messages: 


CPF4282 (Escape) 
CPF5332 (Escape) 
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82B4 


82B5 


82BB 


82EA 


82EE 


Description: The acquire operation issued by your program was not 
successful because a System/36 application program in the System/36 
environment attempted to acquire an ICF program device for 3270 SNA 
program interface tasks. 


Action: 3270 SNA program interface does not support System/36 
application programs. Use an AS/400 program that is not running in 
the System/36 environment. 


Messages: 


CPF4233 (Escape) 
CPF5336 (Escape) 


Description: The acquire operation issued by your program was not 
successful because a 3270 SNA program interface session cannot use 
a SNUF device from an earlier release. 


Action: Delete the SNUF device description, create a new device 
description, and issue the acquire operation again. 


Messages: 
CPF4136 (Escape) 


Description: The acquire operation issued by your program was not 
successful because the program device specified by your program was 
reserved for a program start request from the host. The session was 
not started. 


Action: Specify a device which was not created as being capable of a 
program start request, or create this device again with the correct attri- 
butes. 


Messages: 


CPF4109 (Escape) 
CPF5355 (Escape) 


Description: The open or acquire operation attempted by your 
program was not successful. A format selection of “RECID was speci- 
fied on the ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE command, 
but cannot be used with the ICF file because the RECID DDS keyword 
is not used on any of the record formats in the file. The session was 
not started. 


Action: Close the ICF file. Change the record format selection 
(FMTSLT) parameter to select formats by some means other than 
“RECID, or use a file that has a RECID DDS keyword specified for at 
least one record format. Open the file again. 


Messages: 


CPF4348 (Escape) 
CPF5521 (Escape) 


Description: Your program attempted an open or acquire operation to 
a device that is not supported. Your program tried to acquire a device 
that is not a valid ICF communications type, or it is trying to acquire the 
requesting program device in a program that was not started by a 
program start request. The session was not started. 
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Action: Your program can continue local processing or end. Verify 
that the name of the remote location is specified correctly in the 
RMTLOCNAME parameter on the ADDICFDEVE, CHGICFDEVE, or 
OVRICFDEVE command. If your program was attempting to acquire a 
non-ICF device, use the appropriate interface for that communications 
type. If your program was attempting to acquire a requesting program 
device, verify that your program is running in the correct environment. 


Messages: 


CPF4105 (Escape) 

CPF4223 (Escape) 

CPF4251 (Escape) 

CPF4760 (Escape) 

CPF5038 (Escape) 

CPF5550 (Escape) 

82EF Description: Your program attempted an acquire operation, or an 
open operation that implicitly acquires a session, to a device that the 
user is not authorized to, or that is in service mode. The session was 
not started. 


Action: If the operation was an acquire, correct the problem and issue 
the acquire again. If the operation was an open, close the file, correct 
the problem, then issue the open operation again. To correct an 
authority error, obtain authority for the device from your security officer 
or device owner. If the device is in service mode, wait until machine 
service function (MSF) is no longer using the device before issuing the 
operation again. 


Messages: 


CPF4104 (Escape 
CPF4186 (Escape 
CPF5278 (Escape 
CPF5279 (Escape 


YH Sw NH 


82F5 Description: The open or acquire operation was not successful 
because your program tried to use a format selection option of 
“RMTFMT in the FMTSLT parameter on the ADDICFDEVE or 
OVRICFDEVE command. The session was not started. 


Action: Change the value in the FMTSLT parameter on the 
ADDICFDEVE or OVRICFDEVE command, then issue the open or 
acquire operation again. 


Messages: 


CPF4347 (Escape) 
CPF5515 (Escape) 
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Major Code 83 


Major Code 83 — Session error occurred (the error is recoverable). 


Description: A session error occurred, but the session may still be active. 
Recovery within your program might be possible. 


Action: You can perform the following general actions for all 83xx return 
codes. Specific actions are given in each minor code description. 


¢ Correct the problem and continue processing with the session. If the error 
occurred because of a resource failure on the remote system or because 
the remote system was not active at the time, a second attempt may be 
successful. If the operation is still not successful, your program should end 
the session. 

e Issue an end-of-session function and continue processing without the 
session. 

e End. 


Several of the minor codes indicate that an error condition must be corrected by 
changing a value in the communications configuration or in the file. 


¢ To change a parameter value in the communications configuration, vary the 
configuration off, make the change to the configuration description, then 
vary the configuration on. 

¢ To change a parameter value in the file, use the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command. 


Note: When a parameter can be specified both in the ADDICFDEVE or 
OVRICFDEVE command and in the configuration, the value in the 
ADDICFDEVE or OVRICFDEVE command overrides the value spec- 
ified in the configuration (for your program only). Therefore, in some 
cases, you may choose to make a change with the ADDICFDEVE or 
OVRICFDEVE command rather than in the configuration. 


If no changes are needed in your file or in the configuration, and depending on 
what the return code description says, you should notify the remote location that 
a change is required at that location to correct the error received. 


Code Description/Action 


830B Description: Your program attempted an operation that was not valid 
because the session was not yet acquired or has ended. The session 
may have ended because of a release operation, an end-of-session 
function, or a permanent error. Your program may have incorrectly 
handled a previous error. 


Action: Verify that your program does not attempt any operations 
without an active session. Also verify that your program correctly 
handles the permanent error or session-not-acquired return codes 
(80xx, 81xx, 82xx) it received on previously issued input and output 
operations. To recover from an incorrectly handled error condition, 
your program may or may not be able to issue another acquire opera- 
tion, depending on the return code. 
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830C 


830D 


8311 


8319 


831B 


Messages: 


CPD4079 (Diagnostic) 
CPF4739 (Status) 
CPF5067 (Escape) 
CPF5068 (Escape) 
CPF5070 (Escape) 


Description: Your program received a function-management-header 
(FMH) that was greater than the request unit (RU) size. 


Action: Verify that the host system actually sent the function- 
management-header. If the host system sent only data and no FMH, 
SNUF may have treated a data byte as the FMH length. 


Messages: 
CPF4770 (Notify) 


Description: Your program received a shutdown indication from the 
host system. The host system has begun shutdown procedures, 
although the session is still usable. 


Action: Finish activity for the session and release the session as soon 
as possible so the host system can complete shutdown procedures. 


Messages: 
CPF4771 (Notify) 


Description: Your program attempted an output operation while a 
message containing sense data was waiting to be received. 


Action: Issue an input operation to receive the sense data. 
Messages: 
CPF4772 (Notify) 


Description: The remote program sent a negative-response with 
sense data. 


Action: Issue an input operation to receive the sense data. 
Messages: 
CPF4773 (Notify) 


Description: Your program tried to specify invalid sense data on a 
negative-response function, or it tried to send a negative-response that 
has already been sent to the current chain. The data was not sent. 


Action: Correct your program so that it does not issue the same 
negative-response more than once, and that it sends valid sense data 
on a negative-response function. Valid sense data must be either 0 or 
8 bytes long. To send 8 bytes, the first four bytes must be 0000, 08xx, 
or 10xx, and the remaining four bytes must be in the ranges 0-9, A-F, 
or a-f. If your program chooses to send a negative-response without 
sense data, SNUF automatically sends 08110000 to the remote 
program. 


Messages: 
CPF4774 (Notify) 
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831C 


831E 


831F 


Description: Your program's previous output operation received a 
return code of 0412, indicating that your program must receive informa- 
tion sent by the remote program; however, your program did not handle 
the return code correctly. The current output operation was not suc- 
cessful because your program should have issued an input operation to 
receive the information already sent by the remote program. 


Action: Issue an input operation to receive the previous information. 
Messages: 


CPF4934 (Notify) 
CPF5076 (Notify) 


Description: The operation attempted by your program was not valid, 
or a combination of operations that was not valid was specified. The 
session is still active. The error may have been caused by one of the 
following: 


e Your program issued an operation that is not recognizable or not 
supported by SNUF. 

¢ Your program requested a combination of operations or keywords 
that was not valid, such as a combined write-then-read operation 
with the invite function specified. 

e Your program issued an input operation, or an output operation 
with the invite or allow-write function, for a file that was opened for 
output only. 

e¢ Your program issued an output operation for a file that was opened 
for input only. 

e Your program issued a close operation with a temporary close 
option. 


Action: Your program can try a different operation, issue a release 
operation or end-of-session function, or end. Correct the error in your 
program before trying to communicate with the remote program. 


If the file was opened for input only, do not issue any output operations; 
or, if the file was opened for output only, do not issue any input oper- 
ations, and do not use the invite or allow-write function on an output 
operation. If such an operation is needed, then release the session, 
close the ICF file, and open the file again for input and output. 


Messages: 


CPF4564 (Escape) 

CPF4764 (Notify) 

CPF4766 (Notify) 

CPF4790 (Notify) 

CPF5132 (Escape) 

CPF5149 (Escape) 

Description: Your program specified data or a length for the operation 
that was not valid; however, the session is still active. One of the fol- 
lowing caused the error indication: 


¢ On an output operation, your program tried to send a data record 
that was longer than the MAXRCDLEN value specified for the ICF 
file. 

e The program used a read or write operation that specified a data 
length greater than the record format in the ICF file. 
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e If this was a timer function, the format of the timer interval was not 
HHMMSS. 

e lf a system-defined format was used to specify the operation, or if 
the variable-length-data-record (VARLEN) function was used, then 
the length of the user buffer was not valid. 

e For an SNA 3270 program interface application, the output buffer 
length was less than the length of the required header plus data; 
or, for the SSCP-LU record, the length was greater than the 
maximum allowed. 


Action: If you want your program to recover, try the operation again 
with a smaller data length. If you do not need your program to recover 
immediately, do one of the following: 


¢ Change the record format length in the ICF file, or change the 
record length in your program and compile your program again. 


e For an input operation, specify a data length equal to or less than 
the record format length, or do not specify a length at all. 


e lf the timer function was used, verify that the format of the timer 
interval is HHMMSS. 


e For an output operation that used the variable-length-data-record 
(VARLEN) function, verify that the length specified is less than the 
record length specified for the ICF file when it was opened. 


Messages: 


CPF4762 (Notify) 
CPF4765 (Notify) 
CPF4767 (Notify) 
CPF4786 (Notify) 
CPF4787 (Notify) 
CPF4825 (Notify) 
CPF4827 (Notify) 


8322 Description: Your program tried to issue a request-to-turnaround-with- 
invite function, a negative-response function, or a release operation. 
However, these are not valid while your program is in send state. 


Action: Your program can issue an output operation to continue 
sending data, issue an input operation to begin receiving data, issue an 
end-of-session function to continue local processing, or end. Correct 
the error that caused your program to attempt the operation that was 
not valid. 


Messages: 
CPF4775 (Notify) 


8323 Description: Your program attempted to issue a cancel function when 
data was received for your program. The cancel function is only valid 
in send state. 


Action: Your program can issue an input operation to continue 
receiving data, issue an end-of-session function, or end. Correct the 
error that caused your program to attempt the invalid operation. 
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8324 


8326 


8327 


8329 


832C 


Messages: 
CPF4776 (Notify) 


Description: On an output operation, your program tried to send a 
function-management-header (FMH) with a record that was not the first 
record in the chain. An FMH is valid only at the beginning of a chain; it 
is not valid within the chain. The session is still active. 


Action: Change your program so it sends the FMH with the first 
record in a chain. 


Messages: 
CPF4778 (Notify) 


Description: Your program attempted to issue a cancel function to 
cancel a group of records when no records were previously sent to 
start a group. The cancel function is only valid within a chain; it is not 
valid preceding a chain or between chains. The session is still active. 


Action: Correct the error that caused your program to attempt the 
invalid operation. 


Messages: 
CPF4779 (Notify) 


Description: The input or output operation issued by your program 
was not successful because there was no active transaction. Either the 
transaction has ended, or the transaction was never started. 


Action: If your program wants to start a transaction, it can issue an 

evoke function. Otherwise, it can issue an end-of-session function or 
end. If a coding error in your program caused the error, correct your 
program. 


Messages: 
CPF5098 (Notify) 


Description: An evoke function that was not valid was detected in this 
session. Your program was started by a program start request and, 
therefore, cannot issue any evoke functions in this session. 


Action: To recover, your program can try a different operation or func- 
tion. To issue an evoke function in a different session, first issue an 
acquire operation (using a different program device name), then try the 
evoke function. Otherwise, your program can issue an end-of-session 
function, continue local processing, or end. If a coding error caused 
your program to attempt an evoke that was not valid, correct your 
program. 


Messages: 
CPF5099 (Notify) 


Description: A release operation following an invite function was 
detected. Because your program issued the invite function, it cannot 
issue a release operation to end the invited session. 


Action: Issue an input operation to satisfy the invite function, or issue 
a cancel-invite function to cancel the invite function; then try the release 
operation again. Otherwise, issue an end-of-session function to end 
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the session. If a coding error caused your program to attempt a 
release operation that was not valid, correct your program. 


Messages: 
CPF4769 (Notify) 


832D Description: Following an invite function, your program issued a 
request-to-write indication, a negative-response indication, a cancel 
reply, or an additional invite function. This operation failed because the 
original invite function must first be satisfied by an input operation. 


Action: Issue an input operation to receive the data that was invited. 
Otherwise, issue an end-of-session function to end the session. lf a 
coding error caused your program to attempt a request-to-write indi- 
cation or an additional invite function, correct your program. 


Messages: 
CPF4924 (Notify) 


832F Description: The evoke function or release operation issued by your 
program was not successful because your program attempted the oper- 
ation while the current transaction was still active. The operation was 
not performed, but the session is still active. 


Action: Use the detach function to end the current transaction before 
issuing an evoke function or release operation. Correct the error that 
caused your program to issue an evoke function during an active trans- 
action; then run your program again. 


Messages: 


CPF4780 (Notify) 
CPF4781 (Notify) 


8330 Description: On a successful input operation, your program received 
a cancel function with a turnaround indication. The remote program 
has canceled the group of records it was sending and is now ready to 
receive data from your program. The session is still active. 


Action: Normally, your program should discard the canceled data it 
received from the remote program, as the data may be in error. Your 
program can then issue an output operation. 


Messages: 
CPF4782 (Notify) 


8331 Description: On a successful input operation, your program received 
a cancel function without a turnaround indication. The remote program 
has canceled the group of records it was sending, but it is still in send 
state, and your program is still in receive state. The session is still 
active. 


Action: Normally, your program should discard the canceled data it 
received from the remote program, as the data may be in error. Your 
program should then issue another input operation. 


Messages: 
CPF4783 (Notify) 
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8332 


83B6 


83B7 


83B8 


83E0 


Description: On an input operation, your program received a cancel 
function with a detach indication. The remote program sent some data 
and then canceled the transaction, possibly because it detected an 
error in the data. The session is still active. 


Action: Normally, your program should discard the canceled data it 
received from the remote program, as the data may be in error. If your 
program started the session, it can issue an evoke function to start 
another transaction, issue an end-of-session function to continue local 
processing, or end. If your program was started by a program start 
request from the remote program, it can continue local processing or 
end. 


Messages: 
CPF4784 (Notify) 


Description: On an output operation, your program received an indi- 
cation that the remote program has quiesced the SNA session on 
which this transaction is running by issuing the SNA quiesce-at-end-of- 
chain (QEC) command. The remote program may release the qui- 
esced state at a later time by issuing the SNA release-quiesce 
command. 


Action: Your program can wait and try the output operation again at a 
later time. Otherwise, your program can end the session, continue 
local processing, or end. 


Messages: 
CPF4785 (Notify) 


Description: On a previous operation, your program received an indi- 
cator that the SNA 3270 program interface command code or data flow 
indicator in the common header is not valid, or that the data following 
the common header is not valid. 


Action: Correct the logic in your program that produced the error con- 
dition in the common header or the data, then try the operation again. 


Messages: 


CPF4788 (Notify) 
CPF4789 (Notify) 
CPF4795 (Notify) 


Description: On a previous operation, your program received a 
CLEAR or an UNBIND request with a BIND forthcoming. The host 
system has reset the session. Data sent to or received from the 
remote system may have been lost. The session is now in contention 
state. 


Action: Your program can continue with another input or output opera- 
tion, or it can release the program device and close the ICF file. 


Messages: 
CPF5163 (Notify) 


Description: Your program attempted an operation using a record 
format that was not defined for the ICF file. 


Action: Verify that the name of the record format in your program is 
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correct, then check to see whether the record format is defined in the 
file definition. 


Messages: 
CPF5054 (Notify) 


83E8 Description: Your program attempted to issue a cancel-invite function 
to a session that was not invited. One of the following may have 
occurred: 


e The invite function was implicitly canceled earlier in your program 
by a valid output operation. 

e The invite function was satisfied earlier in your program by a valid 
input operation. 

e Your program had already canceled the invite function, then tried to 
cancel it again. 

¢ Your program never invited the session. 


The session is still active. 


Action: Your program can issue an input or output operation, issue an 
end-of-session function, continue local processing, or end. However, 
you should correct the error that caused your program to attempt the 
cancel-invite to a session that was not invited. 


Messages: 
CPF4763 (Notify) 


83F8 Description: Your program attempted to issue an operation to a 
program device that is marked in error due to a previous I/O or acquire 
operation. Your program may have handled the error incorrectly. 


Action: Release the program device, correct the previous error, then 
acquire the program device again. 


Messages: 
CPF5293 (Escape) 


Failed Program Start Requests 


Message CPF1269 is sent to the system operator message queue when the local 
system rejects an incoming program start request. You can use the message infor- 
mation to determine why the program start request was rejected. 


The CPF1269 message contains two reason codes. One of the reason codes can 
be zero, which can be ignored. If only one nonzero reason code is received, that 
reason code represents the reason the program start request was rejected. If the 
System/36 environment is installed on your AS/400 system, there can be two 
nonzero reason codes. These two reason codes occur when the OS/400 system 
cannot determine whether the program start request was to start a job in System/36 
environment or in the OS/400 environment. One reason code explains why the 
program start request was rejected in the System/36 environment. The other 
explains why the program start request was rejected in the OS/400 environment. 
Whenever you receive two reason codes, you should determine which environment 
the job was to run in and correct the problem for that environment. 


The following lists shows reason codes for failed program start requests. 
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Code Reason Code Description 


401 Program start request is received to a device that is not allocated to an 
active subsystem. 

402 Requested device is currently being held by a Hold Communications 
Device (HLDCMNDEV) command. 

403 User profile is not accessible. 

404 Job description is not accessible. 

405 Output queue is not accessible. 

406 Maximum number of jobs defined by subsystem description are already 
active. 

407 Maximum number of jobs defined by communications entry are already 
active. 

408 Maximum number of jobs defined by routing entry are already active. 

409 Library on library list is exclusively in use by another job. 

410 Group profile cannot be accessed. 

411 Insufficient storage in machine pool to start job. 

412 System value not accessible. 

501 Job description was not found. 

502 Output queue was not found. 

503 Class was not found. 

504 Library on initial library list was not found. 


505 Job description or job description library is damaged. 
506 Library on library list is destroyed. 


507 Duplicate libraries were found on library list. 

508 Storage-pool defined size is zero. 

602 Transaction program-name value is reserved but not supported. 
604 Matching routing entry was not found. 

605 Program was not found. 

704 Password is not valid. 

705 User is not authorized to device. 

706 User is not authorized to subsystem description. 

707 User is not authorized to job description. 

708 User is not authorized to output queue. 

709 User is not authorized to program. 

710 User is not authorized to class. 

711 User is not authorized to library on library list. 

712 User is not authorized to group profile. 

713 User ID is not valid. 

714 Default user profile is not valid. 

715 Neither password nor user ID was provided, and no default user profile 


was specified in the communications entry. 
718 No user ID. 


722 A user ID was received, but a password was not sent. 

723 No password was associated with the user ID. 

725 User ID does not follow naming convention. 

726 User profile is disabled. 

801 Program initialization parameters are present but not allowed. 

802 Program initialization parameter exceeds 2000 bytes. 

803 Subsystem is ending. 

804 Prestart job is inactive or is ending. 

805 WAIT (NO) was specified on the prestart job entry, and no prestart job was 
available. 

806 The maximum number of prestart jobs that can be active on a prestart job 


entry was exceeded. 
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807 
901 
902 
903 
1001 


1002 


1501 
1502 
1503 
1504 
1505 
1506 
1507 
1508 
1509 
1510 
1511 
1512 
1513 
1514 
1515 
1516 
1517 
1518 
1519 
1520 


2111 
2118 
2123 


Prestart job that ended when a program start request was being received. 
Program initialization parameters are not valid. 

Number of parameters for program not valid. 

Program initialization parameters are required but not present. 

System logic error. Notification that an unexpected condition has stopped 
the running of a program or an unexpected return code encountered. 
System logic error. Notification that an unexpected condition has stopped 
the running of a program or an unexpected return code encountered while 
receiving program initialization parameters. 

Character in procedure name not valid. 

Procedure is not found. 

System/36 environment library is not found. 

Library QSSP is not found. 

File QS36PRC is not found in library QSSP. 

Procedure or library name is greater than 8 characters. 

Current library is not found. 

Not authorized to current library. 

Not authorized to QS36PRC in current library. 

Not authorized to procedure in current library. 

Not authorized to System/36 environment library. 

Not authorized to file QS36PRC in System/36 environment library. 

Not authorized to procedure in System/36 environment library. 

Not authorized in library QSSP. 

Not authorized to file QS36PRC in QSSP. 

Not authorized to procedure in QS36PRC in QSSP. 

Unexpected return code from System/36 environment support. 

Problem phase program is not found in QSSP. 

Not authorized to problem phase program in QSSP. 

Maximum number of target programs started (100 per System/36 environ- 
ment). 

Program name is missing or not valid. 

Function-management-header not valid. 

End bracket or end chain missing. 
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Appendix C. Considerations for Host System Programmers 


This appendix contains information intended for 
CICS/VS or IMS/VS host system application pro- 
grammers. It also contains information for 
System/370, System/390, 33xx, and 43xx system 
programmers. Generally, the AS/400 programmer 
does not need the information in this section. 
However, when SNA upline facility (SNUF) is con- 
figured, the AS/400 programmer needs to know 
certain parameter values specified during host 
system generation. For SNA 3270 program inter- 
face host considerations, see Appendix D. 


Generating the Host System With 
VTAM/NCP 


You must complete host system generation before 
you begin communications with the AS/400 
system. With VTAM/NCP, you can generate the 
host system with CICS/VS, IMS/VS, or both, to 
communicate with the AS/400 system in the 
network. See the specific creation considerations 
for the host systems in “Programming for CICS/VS 
Systems” on page C-5 and “Programming for 
IMS/VS Systems” on page C-8. 


Defining Physical Unit 
Parameters 


You must define the AS/400 system during Virtual 
Communications Access Method/Network Control 
Program (VTAM/NCP) generation. Each AS/400 
controller description is represented as a physical 
unit in VTAM. Therefore, each AS/400 controller 
description that SNUF uses requires a physical 
unit definition. 


Note: The following parameters on the physical 
unit definition pertain to a SNUF configuration 
created for a synchronous data link control 
(SDLC) line description. Slight differences may be 
required for token-ring network, Ethernet, and 
X.25 line descriptions. 


PUTYPE parameter = 2 
The physical unit type must be 2. 


ADDR parameter = xx 
This parameter specifies the station address. 
This parameter must be the same as the 
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station address specified in the line 
description (CRTLINSDLC command) or con- 
troller description (CRTCTLHOST commana). 


ISTATUS parameter = ACTIVE / INACTIVE 
This parameter specifies if the physical unit 
should be turned on when its major node is 
turned on. 


MAXDATA parameter = 521 
This parameter specifies the maximum 
amount of data the AS/400 system can 
receive, and must match the value specified 
for the MAXFRAME parameter on the AS/400 
system. The default value shown here (521) 
defines a 512-byte buffer plus 9 bytes for the 
transmission header and the request/response 
header. Other acceptable frame sizes (that 
match a valid MAXFRAME value) are: 265, 
1033, 1466, 1994, and 2057. 


MAXOUT parameter = 7 
This parameter specifies the number of 
frames that Network Control Program (NCP) 
sends to the AS/400 system before waiting for 
a response. For best performance, specify 7. 


DISCNT parameter = YES / NO 
This parameter specifies if VTAM disconnects 
the physical unit when the last logical unit 
session is ended. DISCNT=NO allows the 
AS/400 system to remain active when no ses- 
sions are active. VTAM turns off the physical 
unit when the last SNUF application on the 
line is turned off. DISCNT=YES disconnects 
the AS/400 system when the last session 
ends. SNUF remains active until a deactivate 
operation is performed. DISCNT=YES also 
causes VTAM to ignore the deactivate 
request. If switched lines and more than one 
location are configured, specify DISCNT=YES. 


IDBLK parameter = 056 and IDNUM Parameter 
= number 
These parameters make up the exchange 
identifier. Specify these parameters for a 
switched line only. For the AS/400 system, 
you must specify IDBLK as 056. The IDNUM 
must be the same as the EXCHID parameter 
specified in the line description (CRTLINSDLC 
command). 


C-1 


SSCPFM parameter = USSSCS 
Specify SSCPFM=USSSCS to indicate that 
the AS/400 logical units associated with this 
physical unit use character-coded messages 
to communicate with VTAM. The AS/400 
system requires character-coded messages. 


USSTAB parameter = name 
This parameter specifies the name of an 
unformatted systems services (USS) definition 
table. Since SNUF requires the IBM*-supplied 
definition table, do not specify this parameter. 


Defining Logical Unit Parameters 


Each SNUF session corresponds to an Systems 
Network Architecture (SNA) logical unit and 
requires a logical unit definition in the VTAM cre- 
ation. The following parameters on the logical unit 
definition apply to SNUF. 


LOCADDR parameter = address 
This parameter specifies the local address of 
the session, which is equivalent to a logical 
unit number. You can define up to 255 logical 
units. 


ENCR parameter = NONE 
This parameter specifies the type of 
encryption to be used. The AS/400 system 
does not support encryption for SNUF, so 
specify ENCR=NONE. 


ISTATUS parameter = ACTIVE / INACTIVE 
This parameter specifies if the logical unit is to 
be turned on when the physical unit is turned 
on. 


PACING parameter = count 
This parameter specifies how timing control is 
handled between NCP and the logical unit. 
Pacing controls the rate of data flow between 
the AS/400 program and the host system. It 
allows the receiver to control the rate at which 
the sender sends requests. If timing control is 
necessary, the recommended timing control 
value is 7. 
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Sending the VTAM BIND 
Command 


VTAM sends the BIND command to SNUF. A 
session is not started unless a correctly formatted 
BIND is received by the AS/400 system. The 
parameters for the BIND command for CICS/VS 
and IMS/VS systems are described in Figure C-1. 


Figure C-1 (Page 1 of 2). Parameters for the BIND 
Command 


Byte Value 
(Decimal) (Hex) Meaning 
0 31 SNA BIND request code 
1 01 Format (nonnegotiable) 
2 03, 04 Function management 
profile 
31 03, 04 Transmission services 
profile 
4 90, 91 Multiple request 
units—exception 
response 
AO, At Multiple request 


units—definite response 

BO, B1 Multiple request 
units—definite or excep- 
tion response 


5 90, 91 Multiple request 
units—exception 
response 

AO, Al Multiple request 


units—definite response 

BO, B1 Multiple request 
units—definite or excep- 
tion response 


6,7 2080 Common protocol 
3080 Common protocol 
6080 Common protocol 
7080 Common protocol 
00402 Common protocol 
40402 Common protocol 

8, 93 Transmission services 

use 
104 85 Maximum 


request/response unit 
size (sec to pri) 


Figure C-1 (Page 2 of 2). Parameters for the BIND 
Command 


Byte Value 
(Decimal) (Hex) Meaning 
114 85 Maximum 
request/response unit 
size (pri to sec) 
Notes: 


1 Transmission services profile 03 is not supported if 
message protection is requested. 

2 Protocol is not supported if running in half-duplex 
contention mode. 

3 SNUF does not check these bytes. 

4 The value of these two bytes represent a coded 
hexadecimal size for request units. Each byte is in 
the form ab, where size = (a x 2b). Values can be 
00 through FB (inclusive). If the maximum request 
unit is not specified, a coded size of 89 (4096 byte) 
is assumed. 


For a complete description of the BIND command, 
see the VTAM Programming Guide. 


Example VTAM/NCP Generation 


Figure C-2 on page C-4 is an example 
VTAM/NCP definition of physical and logical units 
on a nonswitched SDLC line. Figure C-3 on 
page C-5 is an example definition for units on a 
switched line. The parameters that correspond to 
SNUF configuration on the AS/400 system are 
highlighted and listed after each figure. 


In Figure C-2 on page C-4: 


This value corresponds to the NRZI param- 
eter on the CRTLINSDLC command. The 
NRZI setting (Yes or No) must be the same 
for both the AS/400 system and the host 
system. 


This value corresponds to the STNADR 
value on the CRTCTLHOST command. 


An active logical unit corresponds to a 
LOCADR specified by the CRTDEVSNUF 
command on the AS/400 system. 


J This name corresponds to the APPID param- 
eter on the CRTDEVSNUF and 
OVRICFDEVE commands. 
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Gl GROUP LCNT=SDLC, 
TYPE=NCP, 
PACING=(3,1), 
ISTATUS=ACTIVE, 
DSCNT=NO, 
PASSLIM=7, 
MAXOUT=7, 
VPACING=(7,1), 
DUPLEX=HALF, 
SPEED=9600, 
PAUSE=0.1, 
CLOCKING=EXT, 
RETRIES=(5,1,2), 
MAXDATA=521, 
SSCPFM=USSSCS 


L023 LINE ADDRESS=028, 
NRZI\=YES, 
SPEE 
PACING=(7,1), 
ISTATUS=ACTIVE 


on SERVICE ORDER=(PU023A, PU023B, PU023C) 

SO er = 
PU023A PU ~—ADDR={C1] s PACING=(7, 1) ,DISCNT=NO 
LU023A1 LU LOCADDR=01, ISTATUS=ACTIVE 
LUO23A2 LU LOCADDR=02, ISTATUS=ACTIVE 
LU023A3 LU LOCADDR=03, ISTATUS=ACTIVE 
LU023A4 LU LOCADDR=04, ISTATUS=ACTIVE 

~ LU023A5 LU LOCADDR=05, ISTA 
LU023A6 LU LOCADDR=06, ISTATUS=ACTIVE 
LU023A7 LU LOCADDR=07 , ISTATUS=ACTIVE 
LU023A8 LU LOCADDR=08, ISTATUS=ACTIVE 
VTAM Application Definition: 
[acs APPL AUTH=(ACQ, PASS) , BUFFACT=25, VPACING=7 
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Figure C-2. VTAM Creation on a Nonswitched SDLC Line 
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SWS36A VBUILD TYPE=SWNET , SUBAREA=3 ,MAXNO=5 ,MAXGRP=5 

PUO24A PU ADDR=C1, PUTYPE=2,, IDBLK=056, IDNUM=| OOEC1 |, 
MAXPATH=2 ,MAXDATA=2057 , PACING=(7,1), 
BATCH=YES, VPACING=0, DISCNT=YES, 
ISTATUS=ACTIVE, PASSLIM=7 ,MAXOUT=7, 
SSCPFM=USSSCS 

PATH1 PATH DIALNO=SS; 9: 18005550123, PID=1 
GRPNM=G2 

LUO24A1 LU LOCADDR=1 

LUO24A2 LU LOCADDR=2 ,, ISTATUS=ACTIVE 

LU024A3 LU LOCADDR=3,, ISTATUS=ACTIVE 

LUO24A4 LU LOCADDR=4, ISTATUS=ACTIVE 


VTAM Start Option: 
SSCPID=(00001 _@ 


Figure C-3. VTAM Creation on a Switched SDLC Line 


In Figure C-3: 


This value corresponds to EXCHID on the 
CRTLINSDLC command. 


This value corresponds to SSCPID on the 
CRTCTLHOST command. On the AS/400 
system, this value is given in hexadecimal 
notation, and on the host system, it is given 
in decimal notation. 


Performance Considerations 


Give attention to the following host configuration 
parameters when defining the physical and logical 
units: 


e The MAXDATA value should equal the 
AS/400 system MAXFRAME parameter value. 

¢ The MAXOUT value should be as 7. 

e A PACING value of zero (0) may be used. If 
this results in extra transmissions due to 
errors, then use a value between 1 and 63. 
The recommended value is 7. 


Give attention to the following host parameters 
when defining Group and Build macros: 


e The BFRS parameter is specified on the 
Group macro. 
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¢ The PASSLIM parameter is specified on the 
Build macro. 


See the Network Control Program: Resource 
Definition Reference for additional information. 


Programming for CICS/VS 
Systems 


The CICS/VS system programmer defines SNUF 
logical units by coding SESTYPE=USERPROG 
and TRMTYPE=3790 in the DFHTCT 
TYPE=TERM macro-instruction. 


To use function management headers in the appli- 
cation programs, specify the appropriate value for 
the INBFMH parameter in the program control 
table. 


You should define the SNUF logical units in the 
CICS/VS terminal control table as 3790 full- 
function logical units. Figure C-4 on page C-6 
shows examples of the table entries created by 
the DFHTCT macro for SNUF logical units. The 
highlighted parameters are listed and described 
after the figure. 
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CICS/VS Stage 1: 


DFHSG PROGRAM=TCP, ACCMETH= (SAM, VTAM, BTAM) , 
DEVICE=(CRLP,DASD, TAPE) , EODI=E0, 
VTAMDEV= (3270, 3770B, INTLU,| 3790, LUTYPE2, LUTYPE3,SCSPRT) , 
BTAMDEV=(L3277, SYS/3, SYS/3D, 3277 , 3286, 3600,3740,3740D) , 
FEATURE=(AUTOANSW, AUTOPOLL,, TRANSPARENCY) , UCTRAN=EBCDIC, 
ANSWRBK= (TERMINAL, AUTOMATIC, EXIDVER) , INITRL=YES, 
BSCODE=(EBCDIC,ASCII) ,WRAPLST=YES , COMPAT=NO, 
LOGREC=YES , AUTOTRN=YES , CHNASSY=YES 


CICS/VS Terminal Control Table: 


DFHTCT TYPE=INITIAL, ACCMETH=(NONVTAM, VTAM) , APPID=|CICS], 
RAMAX=512, RAMIN=512, SUFFIX=OK 


DFHTCT TYPE=TERMINAL, TRMIDNT=L101,| TRMTYPE=3790) , CHNASSY=| YES|, 
SESTYPE=USERPROG|, TRMSTAT=TRANSCEIVE, TIOAL=(512, 4096) , 
BRACKET=YES , ACCME THEVTAM, NETNAME=LU021A2 , BUFFER=|1024 |, 


RUSIZE=[1024 ee 
CICS/VS Destination Control Table: 


[ pret TYPE=INTRA, DESTID=L101, TRIGLEV=1, TRANSID=PGST, 
DESTFAC=TERMINAL 


| prior TYPE=INTRA, DESTID=L202, TRIGLEV=1, TRANSID=PGST, 
DESTFAC=TERMINAL 
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Figure C-4. Sample CICS/VS Table Entries 


In Figure C-4: [J There are two methods to send program 


SNUF sessions are defined to CICS/VS as See QueS eo ie neers aaa 
VTAM 3790 devices. ¢ Define intrapartition destinations in the 


EA The APPID value on the CRTDEVSNUF or eles ve Pestinaliog Cone) table 


OVRICFDEVE commands must match the * Use the ee ee th 
INITIAL DFCTCT macro identifier. Ce ee eee eas 


CICS/VS table definitions. 
CHNASSY=YES allows the CICS/VS 


program to receive records exactly as the _-af. i 
AS/400 program does with BATCH(*NO) on ahs te Lehr estab 
the ADDICFDEVE or OVRICFDEVE onsiderations 


command. CHNASSY=NO matches 
BATCH(*YES) record handling on the 
AS/400 system. 


The evoke-with-detach and write-with-detach oper- 
ations indicate that the AS/400 program no longer 
expects to communicate with the CICS/VS 


f] TRMTYPE=3790 and program that was started. To perform the detach 
SESTYPE=USERPROG define the session function, SNUF sends an end-bracket indicator to 
protocol to be used. the CICS/VS program if it is allowed to send the 

EJ For best performance, the RUSIZE and end-bracket indicator. If SNUF is not allowed to 

send the end-bracket, it sends a turnaround indi- 


BUFFER values should be greater than or 
equal to the RCDLEN value on the cator to the CICS/VS program. In return, SNUF 


CRTDEVSNUEF or OVRICEDEVE commanas. expects an end-bracket indicator without data from 
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CICS/VS. If SNUF does not receive the end- 
bracket indicator or if the indicator is accompanied 
by data, it abnormally ends the session. The 
CICS/VS program controls the end-bracket indi- 
cator by using the LAST parameter on the 
EXEC-CICS SEND command or the DFHTCT 
TYPE=WRITE macro instruction. 


Program-Start-Request 
Considerations 


SNUF accepts program start requests only on 
sessions reserved for the requests. Logical units 
reserved for program start requests must be 
started from the host system using the VARY 
command, the LOGAPPL parameter in the VTAM 


definition, or the CICS/VS ACQ master terminal 
command. 


Use one of the following methods to send program 
start requests to an AS/400 system from CICS/VS: 


¢ Transient data put to a transient data destina- 
tion 
e Interval control START command 


Example CICS/VS Remote Program Start 
Request: The following examples show how a 
CICS/VS program starts an AS/400 application 
program. The example in Figure C-5 uses tran- 
sient data put. The example in Figure C-6 on 
page C-8 uses the interval control START 
command. 


AS/400 I CICS/VS 
Application Program SNUF 4 CICS/VS Application Program 
| 
+——_~— Transient data put 
| *TXTC or*EXEC 
i data 
| 
| | End 
: | 
| i 
! Start task > Newtask 
| | transientdataread 
| i 
| 
| ‘ — Send*TXTC or 
! _ “EXECdata 
| 
| | 
| 
<+—— Start program | 
| l 
Acquire ——n er 
Prepare reply 
i 
Writeendof ——————_——_+ 
transaction | | 
Hy | 
Send data > Receive 
| I 
—_- Return code | End 
End | | 
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Figure C-5. Program Start Request Using the Transient Data Put Operation 
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AS/400 P a 
Application Program SNUF 


CICS/VS 


CICS/VS Application Program 


Interval control 
start with 
terminal ID and 
*TXTC or *EXEC 
data 


Starttask § ———————> 


Interval control 


retrieve to read 
data 
| 
. — Send*TXTC or 
«+ Startprogram i *EXEC data 
| | 
| i 
Acquire ——____|, 
Prepare reply | 
| i 
Write end of 
transaction 
i | 
i Senddata Le Receive 
| 
| i 
«—.— Returncode | 
End | End 
| 
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Figure C-6. Program Start Request Using Interval Control Start Command 


Programming for IMS/VS 
Systems 


You must define each session during IMS/VS 
system creation using the TERMINAL and NAME 
macro instructions. 


e The NAME macro defines the logical terminal 
(LTERM) name of the session. 

e The TERMINAL macro defines session 
parameters to IMS/VS. Each session is 
defined as an SLUTYPEP terminal. 


The following parameters apply to SNUF sessions. 


NAME parameter 
This parameter specifies the VTAM node 
name from VTAM/NCP creation. 


MSGDEL parameter 
This parameter specifies which message 
types IMS/VS should discard for this logical 
terminal: 
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SYSINFO: Specify this attribute to delete all 
system messages before they are sent to your 
program. This attribute is recommended for 
the program start logical units. 


NONIOPCB: Specify this attribute to delete 
the following messages before they are sent 
to your programs: 


e Message switches 

¢ Messages inserted by an IMS/VS program 
to an alternative PCB 

¢ /BROADCAST messages 

e DFS059 TERMINAL status messages 


This attribute is recommended for all systems 
except program start logical units. 


NOTERM: Specify this attribute to send only 
the following messages to your program: 


e Message switches 

¢ Messages inserted by an IMS/VS program 
to an alternative PCB 

e /BROADCAST messages 


e DFS059 TERMINAL status messages 


NONE: Specify this attribute to send all mes- 
sages to your program. 


COMPT1, COMPT2, COMPT3, and COMPT4 


parameters 

These parameters define up to four separate 
components for each session. SNUF provides 
no explicit support for multiple components 
per session. Therefore, define only one com- 
ponent per session. Additional options include 
component protection and blocking. SNUF 
does not provide explicit support for distrib- 
uted presentation or SNA character string pro- 
cessing. Use these options only if the AS/400 
program can handle them. 


OPTIONS parameter 


This parameter specifies the following addi- 
tional parameters: 


Response Mode parameter 
This parameter specifies the response 
mode for this session (see “Operating in 
Terminal Response Mode” on page 5-11 
for more details). 


MFS/NOMFS parameter 
This parameter specifies if message 
format services are provided for this 
session. If you specify message format 


services, the AS/400 application must be 
prepared to handle the data streams. 


ACK/OPTACK parameter 
This parameter specifies the type of 
response required. You must select 
OPTACK for SNUF. If you select ACK, 
the session ends when an update or 
recoverable transaction is attempted. 


BID/NOBID parameter 
This parameter specifies if the VTAM BID 
command is used. 


OPNDST/NOPNDST parameter 
This parameter specifies if sessions can 
be started with the /OPNDST command. 
Select OPNDST for program start ses- 
sions because they may have to be 
started from the host system. 


OUTBUF parameter 
This parameter specifies the maximum 
request unit size for the BIND command. 
SNUF rejects any BIND command with a 
maximum request unit greater than 4096 
bytes (the default value is 256). 


Figure C-7 is a portion of an IMS/VS definition. 
The highlighted parameters correspond to param- 
eters on the OVRICFDEVE and ADDICFDEVE 
commands and are described after the figure. 


COMM RECANY=(4, 2000 ) ,APPID= NS 


OPTIONS=(TIMESTAMP, 2000, FMTMAST) 


TYPE UNITYPE=SLUTYPEP 


TERMINAL NAME=|LU021A1) ,MSGDEL=SYSINFO, OUTBUF=|2000 
OPTIONS=(NORESP, PAGDEL, OPTACK, BID) 


NAME PGMST1 


TERMINAL NAME=|LU021A2|,MSGDEL=SYSINFO, OUTBUF= 
OPTIONS=(NORESP, PAGDEL, OPTACK, BID) 


NAME PGMST2 


TERMINAL NAME=|LU021A3},MSGDEL=NONIOPCB, OUTBUF=|2000 


OPTIONS=(NORSEP, PAGDEL, OPTACK,NOBID) 


NAME LTERMA 
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Figure C-7. Example of IMS/VS Definition Parameters 
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In Figure C-7 on page C-9: 


This name corresponds to APPID on the 
CRTDEVSNUF and OVRICFDEVE com- 
mands. 


f/_ For best performance, the buffer size should 
be large enough to handle the maximum 
user record length sent by the AS/400 
system, as defined by RCDLEN on the 


CRIDEVSNUF or OVRICFDEVE commands. 


In this example, local addresses 1 and 2 
(LU021A1 and LU021A2) are used for 
program start sessions. Local address 3 
(LU021A3) is used for acquired sessions. 


Program Start Request 
Considerations 


SNUF accepts program start requests only on 
sessions reserved for this purpose. Logical units 
that send program start requests to the AS/400 
system must use the MSGDEL=SYSINFO option 
on the TERMINAL macro. 


The logical units reserved for program start 
requests must be started from the host system by 
the VARY command, the LOGAPPL parameter in 
the VTAM definition, or the IMS/VS /OPNDST 
command. 


IMS/VS programs that use the program start 
request must have defined a modifiable alternative 
program control block in the program specification 
block. For example, for the IMS/VS program to 
start a program on an AS/400 system using 
LTERM=S3xXA, it must first perform a Change Call 
(CHNG) operation to set the destination of the 
alternative program control block to S8XA. The 
program then performs an Insert Call (ISRT) oper- 
ation to include the name of the process to be 
started and any security information or parameters 
required. The program can then perform Insert 
Call operations to build an output message. 


The IMS/VS program cannot receive data through 
the alternative program control block. Therefore, 
the program started on an AS/400 system cannot 
reply to the message it received from IMS/VS 
through the same logical unit from which it was 
received. However, the program can acquire 
another session and start a transaction on that 
session to send a reply. 


Example IMS/VS Remote Program Start 
Request: Figure C-8 is an example of how an 
IMS/VS program starts an AS/400 program and 
how the AS/400 program attaches to the IMS/VS 
application program. 


AS/400 . IMS/VS 
Application Program SNUF IMS/VS Application Program 
| 
<«—+~ Insert to alternate 
; I/OPCBor 
| | /BROADCAST 
| ‘ 
+—+ Start program < Write *TXTX or 
| *EXECdata 
| Ends 
Acquire : > | 
l l 
+ Returncode 
l i 
Evoke : > | 
| | 
| Transaction ID > 
+—— Return code Start program | > 
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Figure C-8. Example IMS/VS Remote Program Start Request 
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Appendix D. SNA 3270 Program Interface 


The SNA 3270 program interface for SNA upline 
facility (SNUF) allows an AS/400 application to 
communicate with a host application by sending 
and receiving 3270 data streams. For additional 
information on the 3270 work station, 3270 
devices and 3270 data streams, see the IBM 3270 
Information Display System 3274 Control Unit 
Description and Programmer's Guide and the IBM 
3270 Information Display System, Data Stream 
Programmer's Reference. 


Notes: 


1. SNUF is not intended to emulate a 3174 or 
3274 Control Unit. 


2. If you are using 3270 emulation for BSC, see 
the IBM System/38 Data Communications 
Programmer's Guide and the IBM System/38 
3270 Emulation Reference Manual and User's 
Guide. 


The application programmer constructs the 
AS/400 system application using AS/400 system 
support of programs, intersystem communications 
function (ICF) files and program devices. The pro- 
grams can be coded in any high-level language 
that supports the ICF. The application program 
may be interactive, or it may be started from the 
host system through a program start request. 


A typical AS/400 system interactive application 
might consist of high-level language programs 
(possibly with supporting CL programs) that 
access database, display, and print files. To com- 
municate with a host system through SNA 3270 
program interface, the application program must 
use an ICF file. 


A typical application might open the ICF file, 
acquire the program device session, send and 
receive data from the host application, send or 
receive a DETACH to end the transaction with the 
host application, and release the session with the 
host system. 


For each ICF operation the application program 
should monitor for a successful major or minor 
return code. The data flow is indicated in a 
required 20- or 32-byte common header for both 
sent and received data. The SNA 3270 program 
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interface handles data as a 3274 Type C (remote) 
unit. 


Note: The 3274 models bearing the letter desig- 
nation "C" are: 1C, 21C, 31C, 41C, 51C, and 61C. 
These Type C units operate as remote units using 
either synchronous data link control (SDLC) or 
binary synchronous communications (BSC). The 
application program sends and receives data 
using Write, Erase/Write, Erase/Write Alternate, 
Erase All Unprotected, Read Modified, Read Modi- 
fied All, Read Buffer, and Write Structured Field 
3270 data stream commands. 


ICF File Considerations 


The EMLDEV parameter on the ADDICFDEVE, 
CHGICFDEVE, and OVRICFDEVE commands 
indicates if the device is used to send and receive 
3270 data streams and, if so, whether and how 
the data stream is formatted. 


The EMLDEV parameter specifies both the emu- 
lated device type (with a default of no 3270 emu- 
lation) and 3270 data streams for the following 
supported printers and displays: 


¢ 3278, Models 2, 3, 4, and 5 
¢ 3284 
¢ 3286 
¢ 3287 
¢ 3288 
e 3289 


The second part of the EMLDEV parameter, the 
data format, specifies the format of the 3270 data 
stream being sent and received by the application 
program. In particular, it specifies the form the 
3270 data stream takes in the application I/O 
buffer. The data stream interface with the user 
program can either be formatted or unformatted. 


The unformatted interface presents the 3270 data 
stream to your program in its raw form exactly as 
it is sent from the host system. To use the raw 
data, you should know the following: 


e The format of the 3270 data stream orders 
e The function of the 3270 data stream orders 
e The 3270 addressing scheme 

e¢ The 3270 attribute bit assignments 
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Using the formatted interface reduces the need to 
know the 3270 data stream orders, format, func- 
tion, and so on. 


The formatted interface translates the 3270 data 
stream and builds a 1920, 2560, 3440, or 3564 
character image of the display, which is then pre- 
sented to your application program. The for- 
matted interface allows you to request 3270 
display images with or without field definitions. 
Field definitions are built following the display 
image. For display emulation, each field definition 
identifies the location and characteristics of a par- 
ticular field in the display image. For printer emu- 
lation, a field definition is also used to identify a 
printer order. 


EMLDEV 
The presence of this parameter with values 
other than *NONE indicates that the SNA 
3270 program interface is using this program 
device. The EMLDEV parameter is available 
with the ADDICFDEVE, CHGICFDEVE, and 
OVRICFDEVE commands. 


For the SNA 3270 program interface, the 
parameter may have two parts. The first part 
indicates the intended device for which 3270 
data streams will be transmitted between an 
AS/400 system user application program and 
a host application program. 


*NONE: This default value indicates that the 
program device entry is not used to send and 
receive 3270 data streams. 


*3278 Specifies the data stream is fora 
3277, 3278, or 3279 Display Station. 


*3284 Specifies the data stream is fora 
3284 Printer Device. 


*3286 Specifies the data stream is fora 
3286 Printer Device. 


*3287 Specifies the data stream is fora 
3287 Printer Device. 


*3288 Specifies the data stream is fora 
3288 Printer Device. 


*3289 Specifies the data stream is fora 
3289 Printer Device. 


Note: If a value other than *NONE is speci- 
fied, the second part of the parameter must be 
specified. 
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The second part of the parameter value indi- 
cates whether the 3270 data streams trans- 
mitted are formatted or unformatted and if field 
definitions are included when using formatted 
data. The following values are accepted for 
the second part of the parameter value. 


*UNFORMAT: This default value specifies 
that the application programs send and 
receive data in unformatted form with control 
information embedded. 


*FIELD: Specifies that the AS/400 system 
user application program sends and receives 
a formatted version of the 3270 data streams, 
which are transmitted between the user 
program and the host application program. 
The 3270 data stream will be formatted for the 
application program in Display/Printer Image 
form, with control information followed by field 
definitions of 8 bytes each that indicate the 
location and characteristics of fields or printer 
orders. 


*NOFIELD: Specifies that the AS/400 system 
user application program sends and receives 
a formatted version of the 3270 data streams, 
which are transmitted between the user 
program and a host application program. The 
3270 data stream will be formatted for the 
application program in Display/Printer Image 
form, with control information but without field 
definitions that indicate the location and char- 
acteristics of fields or printer orders. 


*EXTFIELD: Specifies that the AS/400 
system user application program sends and 
receives a formatted version of the 3270 data 
streams, which are transmitted between the 
user program and a host application program. 
The 3270 data stream will be formatted for the 
application program in 3278 display image 
form, with control information followed by 
extended field definitions of 10 bytes each that 
indicate the location and characteristics of 
fields, plus the three extended field attribute 
bytes. 


Note: *EXTFIELD is valid only if *NO is 
specified on the *BATCH parameter and if 
*3278 is specified on the EMLDEV parameter. 


Writing Application Programs 
Using SNA 3270 Program 
Interface 


The AS/400 system application programmer must 
know what is happening in the host application 
and on the host end of the line. Your application 
program must check for, and respond to, ICF 
major/minor return codes resulting from 
input/output operations with the host program, and 
it may monitor for messages. Your program may 
access the data flow, SSCP-LU or LU-LU, indi- 
cated in the 20-or 32-byte common header in the 
buffer. See “38270 Data Flow” on page D-14 fora 
complete list of indicators. (In addition to the 
normal data LU-to-LU and SSCP-to-LU flows, 
there is a special data flow indication to inform the 
program when a query response is received as a 
reply to a get operation during the LU-to-LU flow.) 


As an aid for new applications, it is suggested you 
run a communications line trace of the host appli- 
cation being run to and from the actual 3270 
device. This can be compared against the SNA 
3270 program interface running the same host 
program. This should aid in later debugging of the 
new SNA 3270 program. 


When using the unformatted interface emulating a 
display rather than a printer EMLDEV(*3278 
*“UNFORMAT), the AS/400 system application 
program must be designed to provide a 20-byte 
common header and a 3270 data stream in the 
format the host system is expecting to receive. 
The 3270 data stream will consist of a write of 
user data and necessary control characters asso- 
ciated with a 3278 display device. 


When using the unformatted interface emulating 
either a display or a printer, your program reads 
and extracts user data from the 3270 display or 
printer data stream. 


When using the formatted interface 
EMLDEV(*32xx *NOFIELD), EMLDEV(*32xx 
*“FIELD), or EMLDEV(*3278 *EXTFIELD), your 
program reads the data in the common header, 
display or printer image, and field definitions on a 
formatted read. It changes the necessary fields 
before returning the same structures and data on 
a formatted write to the host system. 


The normal display or printer image you receive 
when working with the formatted interface is a 
1920-byte image. For non-3278 displays this 
value is always 1920. It is possible to receive 
larger images from the host application program. 
For 3278 displays the value may be 1920, 2560, 
3440, or 3564 bytes. This is specified on byte 24 
on the BIND command received from the host 
system. See Figure D-12 on page D-14 for more 
information on the BIND command received from 
the host system. Also, any display image 
received on the SSCP-LU flow is not more than 
1920 bytes. This applies to images received 
before or after the BIND command. The block 
size in the formatted header informs you of the 
image size. 


When your program acquires a program device 
specified for SNA 3270 program interface 
(Display) and sign-on text is sent to the host 
system with an application identifier (other than 
“USER) for a host application program, SNUF 
expects a BIND command from the remote 
system. When you specify the application identi- 
fier parameter as “USER on the ICF device entry, 
SNUF does not send a logon command to the 
host system. Instead, the SNA 3270 program 
interface receives and handles SSCP-LU 
USSMSG messages including sending a negative 
response, if appropriate. If your application 
program sends a logon command to the host 
system after receiving the USSMSG message, 
SNUF sends a positive response to the USSMSG 
message and then issues the logon command to 
the host system. An application identifier of 
“USER is only meaningful if you are using the 
3270 program interface. 


All USSMSG messages sent by the host to a SNA 
Upline Facility 3270API program, with the applica- 
tion identifier option set to “USER, must be 
received by the AS/400. This is done by using a 
READ operation instead of a READ FROM 
INVITED PROGRAM DEVICE operation. 


If the 3270API application sends the host a logon 
message, the message was sent using a PUT 
operation instead of a PUT-INVITE operation. 


When your program acquires a program device 
specified for SNA 3270 program interface 
(Printer), SNUF expects a BIND command without 
sending sign-on text. 
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In general, an AS/400 system application program 
must be designed to handle two types of data 
streams sent from the host system: 


e¢ A data stream from a host write operation 
e¢ A data stream that contains a host read 


For either, the user program must respond by 
doing a Read command to receive the data, the 
3270 command, or both. 


Unformatted Program Interface 


When EMLDEV(*32xx *UNFORMAT) has been 
specified on the ADDICFDEVE or CHGICFDEVE 
command, the user program will receive and send 
a common header followed by the unformatted 
3270 data stream. In this case, the only signif- 
icant fields in the common header are the 3270 
command and the data flow indication. The 
common header for the unformatted program 
interface is illustrated in Figure D-1. 


Command 


Data 
Flow 


21 


ee i. 


RSLS175-2 


Figure D-1. Common Header for Unformatted Program Interface (20 Bytes) 


The common header fields have the following 
meanings: 


¢ Byte 1: The CMD (Command) has the same 
meaning as in the 3270 data stream. Byte 1 
is copied from the 3270 data stream received 
by the AS/400 system from the host system. 
On a write to the host system it may be set or 
changed by the user program. 


¢ Byte 19: This field indicates the data flow 
that is currently active, either LU-LU or 
SSCP-LU. See “3270 Data Flow” on 
page D-14. 


Figure D-2 is an unformatted 3270 data stream 
received from the System/370 host system on a 
host write operation (as it would be received in the 
user program buffer following the header): 


D-4 sSNA Upline Facility Programming V4R1 


Figure D-2. AS/400 Program Read (To a Write 
Command) 


Functional 
Description 


Write, Erase/Write, 
Erase/Write Alternate, 
Write Structured Field 


Data Stream 
Command/Order Bytes 
Write-Type 1 
Command Code 


WCC 1 Write control char- 


acter 


Printout format orders 
or buffer control 
orders with data 


Orders and data N 


For a description of printer formatting orders (NL, 
EM, FF, SI, and CR), buffer control orders (SBA, 
SF, IC, PT, RA, EUA), and orders for Structured 
Field and Attribute processing (SFE, MF, SA), see 
the IBM 3270 Information Display System 3274 
Control Unit Description and Programmer's Guide. 


Figure D-3 on page D-5 is a 3270 data stream for 
a System/370 host read request operation: 


Figure D-3. AS/400 Read (To a Read Request 
Command) 


Figure D-5. AS/400 Program Write (To a Read Modi- 
fied Command) 


Functional 
description 


Read Buffer, Read 
Modified, or Read 
Modified All 


Data Stream 
Command/Order _ Bytes 


Read-Type 1 
Command Code 


Figure D-4 is a 3270 data stream on a write oper- 
ation from an AS/400 system program in response 
to a System/370 host Read Buffer command: 


Figure D-4. AS/400 Program Write (To a Read Buffer 
Command) 


Functional 
description 


Data Stream 
Command/Order Bytes 


AID 1 No AID generated 
(Display), No AID 
(Printer), Enter, PF or 


PA 


Cursor Address 2 Cursor Address 


SF 1 Start Field, or Start 
Field Extended 
Field Attribute 1 Attribute Character 
Character 
Data data Data 
length 
SF 1 Start Field, or Start 
Field Extended 
Field Attribute 1 Attribute Character 
Character 
Data data Data 
length 


Figure D-5 is a 3270 data stream on a write oper- 
ation from an AS/400 system program in response 
to a System/370 host Read Modified or Read 
Modified All command. In this data stream, only 
modified data fields are expected by the host 
system. 


Note: The AID is other than the CURSR SEL 
key, a PA key or the CLEAR key. 


Functional 
description 


Data Stream 
Command/Order Bytes 


AID 1 No AID generated 
(Display), No AID 


(Printer), Enter, PF key 


Cursor Address 2 Cursor Address 


SBA 1 Set Buffer Address 
Buffer Address 2 Buffer Address 
Data data Data 

length 
SBA 1 Set Buffer Address 
Buffer Address 2 Buffer Address 
Data data Data 

length 


If the AID is a PA key or the CLEAR key, then the 
3270 data stream in Figure D-6 is written from an 
AS/400 system program in response to a 
System/370 host Read Modified or Read Modified 
All command: 


Figure D-6. AS/400 Program Write (To a Read Modi- 
fied Command) 


Functional 
description 


PA key or CLEAR key 


Data Stream 
Command/Order Bytes 


AID 1 


The AID is for the CURSR SEL key. 


Figure D-7. AS/400 Program Write (To a Read Modi- 
fied Command) 


Functional 
description 


Data Stream 
Command/Order Bytes 


Cursor Select 1 No AID generated 
AID (Display), No AID 
(Printer), Enter, PF key 


Cursor Address 2 Cursor Address 


SBA 1 Set Buffer Address 
Buffer Address 2 Buffer Address 
SBA 1 Set Buffer Address 


Buffer Address 2 Buffer Address 
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Formatted Program Interface 


When EMLDEV (*32xx *“NOFIELD), EMLDEV 
(*32xx *FIELD), or EMLDEV (*3278 *EXTFIELD) 
is specified on the ADDICFDEVE, CHGICFDEVE, 
or OVRICFDEVE command, the user program 
receives and sends 3270 data stream information 
through the formatted program interface. 


EMLDEV (*32xx *NOFIELD): When 
EMLDEV (*32xx *NOFIELD) is specified on the 
ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE 
command, the formatted program interface has 
the buffer content shown in Figure D-8. 


1 
i Display 
Command Control Attention | Station rere 

Character Identifier or 

Printer | 
Block ee Line oe Error Position pele Reserved Common Header 
Code Flow 
(20 bytes) 
7 | 


21 


3270 Screen Expandedwith the 
3270 Attributes Imbedded as 
Received 


Display/Printer Image 
(maximum 3564 bytes) 


RV2W535-0 


Figure D-8. Common Header and Buffer for Formatted Program Interface—EMLDEV (*3278 *NOFIELD) 


In the common header, certain fields are set by 
the AS/400 system when a 3270 data stream is 
received from the host system, some are set by 
the user program when sending a 3270 data 
stream to the host system, and some are set by 
both. 


If the first operation performed by the user 
program is a write, fields in the header that are set 
only by the AS/400 system should be binary zero. 


The common header fields have the following 
meanings: 


¢ Bytes 1-3: The Command (CMD), Write 
Control Character (WCC), and Attention Iden- 
tifier (AID) have the same meaning as in the 
3270 data stream. For a description, see the 
IBM 3270 Information Display System 3274 
Control Unit Description and Programmer's 
Guide. Bytes 1-3 are copied from the 3270 
data stream received by AS/400 system from 
the host system. On a write to the host 
system, they may be set or changed by the 
user program. 
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¢ Byte 4: Display Station or Printer is the 
device type. If this field is the character 0, 
this device is a display. If this field is the 
character 1, this device is a printer. The 
AS/400 system sets this field when the first 
3270 data stream is received from the host 
system. The user program should return the 
same value on subsequent writes to the host 
system. 


e Bytes 5-6: Cursor Position is the position 
(binary 1 through block size) where the cursor 
is located. This value is set by the AS/400 
system when a 3270 data stream is received 
from the host system (if an insert cursor order, 
IC, is not found in the data stream, the cursor 
remains at its last location) and set or 
changed on a user program write to the host 
system. 


¢ Bytes 7-12: These are set only when the 
user has specified EMLDEV(*32xx *FIELD or 
“EXTFIELD) on the ADDICFDEVE, 
CHGICFDEVE, or OVRICFDEVE command. 


¢ Bytes 13-14: Block Size is a binary number 


indicating the size (in bytes) of the data in the 
display or printer image. This value, added to 
the header length, indicates the last position in 
the input buffer into which data from the host 
system is placed. 


If the block size is less than 1920, all bytes in 
the display image buffer, after the block size, 
contain nulls. For displays, the value size 
may increase from 1920 bytes to 2560, 3440, 
or 3564 bytes if the alternate screen size is 
used. For printers, this value can be 0 
through 1920. 


Byte 15: Line (LIN) is the size of the char- 
acter print line and only applies to printers. 
This value indicates how data should be for- 
matted if it is printed. Possible line values 
are: 


1 for 40 characters per line 

2 for 64 characters per line 

3 for 80 characters per line 

4 for unformatted (Line size is determined 
by the new line, NL, print order) 


Byte 16: Return Code (RET) contains return 
code information about translation. This field 
should always be set to binary zero when 
issuing read or write operations. Possible 
values are: 


‘00'X No condition. 

‘01'X Not enough space for all field 
entries; some created but more are 
possible. This value applies to 
Read operations only. 

02'X Incorrect attention identifier key 
field; this value applies only to 
write operations. 


'03'X Incorrect cursor position; this 
value applies only to write oper- 
ations. 


04'X Attributes changed in the display 
image buffer to a value other than 
01; this value applies only to write 
operations. 


05'X Number of entries is larger than 
what was previously returned; this 
value applies only to write oper- 
ations. 


¢ Bytes 17-18: Error Position (ERR) is a 
binary number indicating the error position in 
the display image buffer that corresponds to 
the return code. For a display device, this 
position is that of an attribute. For a printer, 
this position may be either the position of an 
attribute or the position of a printer order. 

This field applies only when the value returned 
in the return code position is 1 or 4. 


¢ Byte 19: This field indicates the data flow 
that is currently active, either LU-LU, QUERY 
REPLY, or SSCP-LU. See “3270 Data Flow” 
on page D-14. 


¢ Byte 20: This is a reserved space and must 
contain binary zeros. 


Display Image: The display image in Figure D-8 
on page D-6 contains 1920, 2560, 3440, ora 
maximum of 3564 bytes of attributes and display 
or printer data. Each attribute occupies one 
location in the buffer. An attribute character 
defines the beginning of a field and contains char- 
acteristics about the field. The attribute character 
has the same meaning as bits 2 - 7 of the attri- 
bute character in the 3270 data stream. Fora 
description of the attribute character bit definitions, 
see the /BM 3270 Information Display System 
3274 Control Unit Description and Programmer's 
Guide. 


When EMLDEV(*32xx *NOFIELD) is specified, the 
user program must update the attribute byte and 
the field itself when it modifies fields to be sent to 
the host system. Bit 7 of the attribute byte must 
be set to indicate a modified field. 


EMLDEV (*32xx *FIELD): when 
EMLDEV(*32xx *FIELD) is specified on the 
ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE 
command, the formatted program interface has 
the buffer content shown in Figure D-9 on 

page D-8. 
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: Display 
Write Attention | Station Cursor Number of Number of Number of 
Control Identifier | or Position Entries Entries Left Last Attribute 
Character Printer Entry 
| | | 
Block Size Line sl Error Position ae Reserved Common Header 
(20 bytes) 


21 


3270 Screen Expanded with the 
3270 Attributes Imbedded as 
Received 


Display/Printer Image 
(maximum 3564 bytes) 


1941 


Position Field Length fe) MDT 


ATT | Reserved 


Field Definition(s) 
(8 bytes each) 


1949 


Field Definitions Received 
if EMLDEV(XXXX*FIELD) 


1957 


1965 


ie 


RV2W538-0 


Figure D-9. Common Header and Buffer for Formatted Program Interface—EMLDEV (*32xx *FIELD) 


In the common header, certain fields are set by 
the AS/400 system when a 3270 data stream is 
received from the host system, some are set by 
the user program when sending a 3270 data 
stream to the host system, and some are set by 
both. 


If the first operation performed by the user 
program is a write, fields in the header that are set 
only by the AS/400 system should be binary zero. 


The common header fields have the following 
meanings: 


e¢ Bytes 1-3: The Command (CMD), Write 
Control Character (WCC), and Attention Iden- 
tifier (AID) have the same meaning as in the 
3270 data stream. For a description, see the 
IBM 3270 Information Display System 3274 
Control Unit Description and Programmer's 
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Guide. Bytes 1-3 are copied from the 3270 
data stream received by AS/400 system from 
the host system. On a write to the host 
system, they may be set or changed by the 
user program. 


¢ Byte 4: Display Station or Printer is the 


device type. If this field is the character 0, 
this device is a display. If this field is the 
character 1, this device is a printer. The 
AS/400 system sets this field when the first 
3270 data stream is received from the host 
system. The user program should return the 
same value on subsequent writes to the host 
system. 


e Bytes 5-6: Cursor Position is the position 


(binary 1 through block size) where the cursor 
is located. This value is set by the AS/400 
system when a 3270 data stream is received 


from the host system (if an insert cursor order, 
IC, is not found in the data stream, the cursor 
remains at its last location) and set or 
changed on a user program write to the host 
system. 


Bytes 7-8: Number of Entries is a binary 
number indicating the total number of field 
definitions including attribute entries and 
printer order entries. When data is received 
from the host system, the AS/400 system 
returns the number of entries created. Ona 
write to the host system, the user program 
sets this value to the number of entries to be 
processed. 


If this value is zero when transmitting data, 
the AS/400 system returns only the attention 
identifier, cursor position, and any host set 
modified data tag fields to the host system. 


If this field is changed to a value greater than 
the value returned with a previously received 
3270 data stream from the host system, an 
error return code is created. 


Bytes 9-10: Number of Entries Left is a 
binary number indicating the total number of 
field definitions that could not be built in the 
user buffer. This number includes both attri- 
bute entries and printer order entries. 


This value is set only when a return code 
result indicates not enough space in the buffer 
to build field definitions for all fields and printer 
orders. 


Bytes 11-12: Number of Last Attribute Entry 
is a binary number indicating the number of 
the field definition that identifies the last attri- 
bute in the display image buffer. If the display 
is not formatted (contains no attributes), this 
value is zero. 


Bytes 13-14: Block Size is a binary number 
indicating the size (in bytes) of the data in the 
display or printer image. This value, added to 
the header length, indicates the last position in 
the input buffer into which data from the host 
system is placed. 


If the block size is less than 1920, all bytes in 
the display image buffer, after the block size, 
contain nulls. For displays, the value size 
may increase from 1920 bytes to 2560, 3440, 
or 3564 bytes if the alternate screen size is 
used. For printers, this value can be 0 
through 1920. 


¢ Byte 15: Line (LIN) is the size of the char- 


acter print line and only applies to printers. 
This value indicates how data should be for- 
matted if it is printed. Possible line values 
are: 


1 for 40 characters per line 

2 for 64 characters per line 

3 for 80 characters per line 

4 for unformatted (Line size is determined 
by the new line, NL, print order) 


Byte 16: Return Code (RET) contains return 
code information about translation. This field 
should always be set to binary zero when 
issuing read or write operations. Possible 
values are: 


00'X No condition. 

01'X Not enough space for all field 
entries; some created but more are 
possible. This value applies to 
Read operations only. 

02'X Incorrect attention identifier key 
field; this value applies only to 
write operations. 


03'X Incorrect cursor position; this 
value applies only to write oper- 
ations. 


04'X Attributes changed in the display 
image buffer to a value other than 
01; this value applies only to write 
operations. 

"05'X Number of entries is larger than 
what was previously returned; this 
value applies only to write oper- 
ations. 


Bytes 17-18: Error Position (ERR) is a 
binary number indicating the error position in 
the display image buffer that corresponds to 
the return code. For a display device, this 
position is that of an attribute. For a printer, 
this position may be either the position of an 
attribute or the position of a printer order. 

This field applies only when the value returned 
in the return code position is 1 or 4. 


Byte 19: This field indicates the data flow 
that is currently active, either LU-LU, QUERY 
REPLY, or SSCP-LU. See “3270 Data Flow” 
on page D-14. 


Byte 20: This is a reserved space and must 
contain binary zeros. 
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Display Image: The display image in Figure D-9 
on page D-8 contains 1920, 2560, 3440, ora 
maximum of 3564 bytes of attributes and display 
or printer data. Each attribute occupies one 
location in the buffer. An attribute character 
defines the beginning of a field and contains char- 
acteristics about the field. The attribute character 
has the same meaning as bits 2-7 of the attribute 
character in the 3270 data stream. Fora 
description of the attribute character bit definitions, 
see the /BM 3270 Information Display System 
3274 Control Unit Description and Programmer's 
Guide. 


When EMLDEV(*32xx *FIELD) is specified, the 
user program must update the attribute byte, the 
field itself, and the field definition when it modifies 
fields to be sent to the host system. 


The modified data tag byte (MDT) of the field defi- 
nition entry must be set to '01'X, or an error (RET 
= 4) will occur. 


Field Definitions: The field definitions in 

Figure D-9 describe the input and output field for 
display devices and printer orders for printer 
devices. Field definitions apply when 
EMLDEV(*32xx *FIELD) has been specified. 


A field definition entry is created for each field in 
the display image and is also created for printer 
orders in a printer data stream, unless the orders 
are consecutive. Field definitions are ordered 
from position 1 through 1920, 2560, 3440, or 3564 
of the display image. 


Whenever data is received from the host system, 
fields in the display image may be overwritten. 
When an attribute for a field is overwritten, the 
field definition corresponding to that field is 
removed. If the field definition is for an attribute, 
its format is as follows: 


¢ Bytes 1-2: Position is a binary number that 
defines the relative position from the begin- 
ning of the display image to the first character 
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of the field. The values for position can range 
from 1 through 1920, 2560, 3440, or 3564. 


¢ Bytes 3-4: Field Length is a binary number 
indicating the length of the field defined by the 
attribute. This length does not include the 
attribute byte. 


¢ Byte 5: I/O indicates whether the field is an 
unprotected field or a protected field. The I/O 
entry is the character 0 if the field is unpro- 
tected and the character 1 if it is protected. 


¢ Byte 6: MDT (Modified Data Tag) indicates 
whether the field is marked as changed. MDT 
is '01'X if the field is changed or '00'X if the 
field is unchanged. 


When receiving data, the MDT value is '01'X if 
the host system turned on the MDT bit in the 
attribute, or if the MDT was on from a pre- 
vious translation and the write control char- 
acter (WCC) does not indicate that the MDT 
should be reset. Otherwise the MDT value is 
‘00'*X. 

When sending data, the value must be 
changed from '00'X to '01'X if the unprotected 
field was changed. If the MDT value is 
changed to a value other than '01'X or is 
changed to '01'X for a protected field, the 
change is ignored. 


¢ Byte 7: ATT (Attribute) is a copy of the Attri- 
bute of this field. For a description of the attri- 
bute character bit definitions, see the /BM 
3270 Information Display System 3274 Control 
Unit Description and Programmer's Guide. 


¢ Byte 8: This is a reserved space and must 
contain binary zeros. 


EMLDEV (*3278 *EXTFIELD): When 
EMLDEV (*3278 *EXTFIELD) is specified on the 
ADDICFDEVE, CHGICFDEVE, or OVRICFDEVE 
command, the formatted program interface has 
the buffer content shown in Figure D-10 on 
page D-11. 


1 
e Display 
Write ; Number of 
Attention Station Cursor Number of Number of , 
Command |Control Identifier or Position Entries Entries Left Past Airibute 
Character Pri Entry 
rinter 
| | | | 
; : Return aa Data . 
Block Size Line Code Error Position Flow Reserved Field Length Reserved 
| | | | 
Common Header 
Reserved (32 bytes) 
33 
3270 Screen Expandedwith the 
3270 Attributes Imbeddedas F 
Received. Extended Field paket ot) Mest 
Attributes will be in the (maximum yles) 
Field Definition Records Only. 
1953 oa q 7 Field Definition(s) 
Position i High- Field 
Field Length vO MDT ATT Color light Validation (10 bytes each) 
1963 Field Definitions 
Received 
EMLDEV(3278 
1973 *EXTFIELD) 
1983 
RV2W536-0 


Figure D-10. Common Header and Buffer for Formatted Program Interface—EMLDEV (*3278 *EXTFIELD) 


In the common header, certain fields are set by 
the AS/400 system when a 3270 data stream is 
received from the host system, some are set by 
the user program when sending a 3270 data 
stream to the host system, and some are set by 
both. 


If the first operation performed by the user 
program is a write, fields in the header that are set 
only by the AS/400 system should be binary zero. 


The common header fields have the following 
meanings: 


¢ Bytes 1-3: The Command (CMD), Write 
Control Character (WCC), and Attention Iden- 


tifier (AID) have the same meaning as in the 
3270 data stream. For a description, see the 
IBM 3270 Information Display System 3274 
Control Unit Description and Programmer's 
Guide. Bytes 1-3 are copied from the 3270 
data stream received by AS/400 system from 
the host system. On a write to the host 
system, they may be set or changed by the 
user program. 


Byte 4: Display Station or Printer is the 
device type. If this field is the character 0, 
this device is a display. If this field is the 
character 1, this device is a printer. The 
AS/400 system sets this field when the first 
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3270 data stream is received from the host 
system. The user program should return the 
same value on subsequent writes to the host 
system. 


Bytes 5-6: Cursor Position is the position 
(binary 1 through block size) where the cursor 
is located. This value is set by the AS/400 
system when a 3270 data stream is received 
from the host system (if an insert cursor order, 
IC, is not found in the data stream, the cursor 
remains at its last location) and set or 
changed on a user program write to the host 
system. 


Bytes 7-8: Number of Entries is a binary 
number indicating the total number of field 
definitions including attribute entries and 
printer order entries. When data is received 
from the host system, the AS/400 system 
returns the number of entries created. Ona 
write to the host system, the user program 
sets this value to the number of entries to be 
processed. 


If this value is zero when transmitting data, 
the AS/400 system returns only the attention 
identifier, cursor position, and any host set 
modified data tag fields to the host system. 


If this field is changed to a value greater than 
the value returned with a previously received 
3270 data stream from the host system, an 
error return code is created. 


Bytes 9-10: Number of Entries Left is a 
binary number indicating the total number of 
field definitions that could not be built in the 
user buffer. This number includes both attri- 
bute entries and printer order entries. 


This value is set only when a return code 
result indicates not enough space in the buffer 
to build field definitions for all fields and printer 
orders. 


Bytes 11-12: Number of Last Attribute Entry 
is a binary number indicating the number of 
the field definition that identifies the last attri- 
bute in the display image buffer. If the display 
is not formatted (contains no attributes), this 
value is zero. 


Bytes 13-14: Block Size is a binary number 

indicating the size (in bytes) of the data in the 
display or printer image. This value, added to 
the header length, indicates the last position in 
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the input buffer into which data from the host 
system is placed. 


If the block size is less than 1920, all bytes in 
the display image buffer, after the block size, 
contain nulls. For displays, the value size 
may increase from 1920 bytes to 2560, 3440, 
or 3564 bytes if the alternate screen size is 
used. For printers, this value can be 0 
through 1920. 


Byte 15: Line (LIN) is the size of the char- 
acter print line and only applies to printers. 
This value indicates how data should be for- 
matted if it is printed. Possible line values 
are: 


1 for 40 characters per line 

2 for 64 characters per line 

3 for 80 characters per line 

4 for unformatted (Line size is determined 
by the new line (NL) print order) 


Byte 16: Return Code (RET) contains return 
code information about translation. This field 
should always be set to binary zero when 
issuing read or write operations. Possible 
values are: 


00'X No condition. 

01'X Not enough space for all field 
entries; some created but more are 
possible. This value applies to 
Read operations only. 

02'X Incorrect attention identifier key 
field; this value applies only to 
write operations. 


03'X Incorrect cursor position; this 
value applies only to write oper- 
ations. 


04'X Attributes changed in the display 
image buffer to a value other than 
01; this value applies only to write 
operations. 

05'X Number of entries is larger than 
what was previously returned; this 
value applies only to write oper- 
ations. 


Bytes 17-18: Error Position (ERR) is a 
binary number indicating the error position in 
the display image buffer that corresponds to 
the return code. For a display device, this 
position is that of an attribute. For a printer, 
this position may be either the position of an 
attribute or the position of a printer order. 


This field applies only when the value returned 
in the return code position is 1 or 4. 


¢ Byte 19: This field indicates the data flow 
that is currently active, either LU-LU, QUERY 
REPLY, or SSCP-LU. See “3270 Data Flow” 
on page D-14. 


¢ Byte 20: This is a reserved space and must 
contain binary zeros. 


¢ Byte 21-22: Field Length is a binary number 
indicating the length of each field definition 
that follows the image. 


¢ Byte 23-32: This is a reserved space and 
must contain binary zeros. 


Display Image: The display image in 

Figure D-10 on page D-11 contains 1920, 2560, 
3440, or a maximum of 3564 bytes of attributes 
and display data. Each attribute occupies one 
location in the buffer. An attribute character 
defines the beginning of a field and contains char- 
acteristics about the field. The attribute character 
has the same meaning as bits 2-7 of the attribute 
character in the 3270 data stream. Fora 
description of the attribute character bit definitions, 
see the /BM 3270 Information Display System 
3274 Control Unit Description and Programmer's 
Guide. 


When EMLDEV(*3278 *EXTFIELD) is specified, 
the user program must update the attribute byte, 
the field itself, and the field definition when it mod- 
ifies fields to be sent to the host system. 


The modified data tag byte (MDT) of the field defi- 
nition entry must be set to '01'X, or an error (RET 
= 4) will occur. 


Field Definitions: The field definitions in 

Figure D-10 describe the input and output field for 
display devices and printer orders for printer 
devices. Field definitions apply when 
EMLDEV(*3278 *EXTFIELD) has been specified. 


A field definition entry is created for each field in 
the display image. Field definitions are ordered 
from position 1 through 1920, 2560, 3440, or 3564 
of the display image. 


Whenever data is received from the host system, 
fields in the display image may be overwritten. 
When an attribute for a field is overwritten, the 
field definition corresponding to that field is 


removed. lf the field definition is for an attribute, 
its format is as follows: 


Bytes 1-2: Position is a binary number that 
defines the relative position from the begin- 
ning of the display image to the first character 
of the field. The values for position can range 
from 1 through 1920, 2560, 3440, or 3564. 


Bytes 3-4: Field Length is a binary number 
indicating the length of the field defined by the 
attribute. This length does not include the 
attribute byte. 


Byte 5: I/O indicates whether the field is an 
unprotected field or a protected field. The I/O 
entry is the character 0 if the field is unpro- 
tected and the character 1 if it is protected. 


Byte 6: MDT (Modified Data Tag) indicates 
whether the field is marked as changed. MDT 
is '01'X if the field is changed or '00'X if the 
field is unchanged. 


When receiving data, the MDT value is '01'X if 
the host system turned on the MDT bit in the 
attribute, or if the MDT was on from a pre- 
vious translation and the write control char- 
acter (WCC) does not indicate that the MDT 
should be reset. Otherwise the MDT value is 
‘00'*X. 

When sending data, the value must be 
changed from '00'X to '01'X if the unprotected 
field was changed. If the MDT value is 
changed to a value other than '01'X or is 
changed to '01'X for a protected field, the 
change is ignored. 


Byte 7: ATT (Attribute) is a copy of the Attri- 
bute of this field. For a description of the attri- 
bute character bit definitions, see the /BM 
3270 Information Display System 3274 Control 
Unit Description and Programmer's Guide. 


Byte 8: Extended color (blue, red, pink, 
green, turquoise, yellow, and white); attribute 
type '42'X. For a description of the extended 
attributes, see the /BM 3270 Information 
Display System 3274 Control Unit Description 
and Programmer's Guide. 


Byte 9: Extended highlighting (blink, reverse 
video, and underline); attribute type '41'X. For 
a description of the extended attributes, see 
the IBM 3270 Information Display System 
3274 Control Unit Description and Program- 
mer's Guide. 
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¢ Byte 10: Field validation (mandatory fill, man- 
datory entry, and trigger) attribute defines the 
validation properties of the field in the display 
image. For a description of the field validation 
attribute see the IBM 3270 Information Display 
System, Data Stream Programmer's Refer- 
ence. 


Figure D-11. BIND Command Byte 14 Values 


3270 Data Flow 


Byte 19 of the common header contains a data 
flow indication. The hexadecimal codes and their 
descriptions are: 


'FO'X LU-LU. Data flow. 

'F1'X LU-LU. Query reply received. Data 
flow. 

'F9O'X SSCP-LU. Data flow. 


The formatted program interface allows an addi- 
tional indicator, which is the query reply received 
(‘F1'X) indicator. When a reply is received by the 
application program, it must be sent to the host 
system with the indicator set to 'F1'X. The reply is 
provided by the 3270 translation function in 
response to a query received from the host 
system. 


Host System Programming 
Considerations 


There are considerations for the SNA BIND 
command, depending on the emulated device 
entered for the EMLDEV parameter. 


Three types of LU-LU sessions are supported. 
These are: 


The device is a printer and the 
data stream is the SNA character 
string (SCS). 

The device is a keyboard/display 
and the data stream is in the 3270 
data stream compatibility (DSC) 
mode format. 

The device is a printer and the 
data stream is in the 3270 DSC 
mode format. 


Type 1 


Type 2 


Type 3 


Depending on the device and formatted or unfor- 
matted data specified for the EMLDEV parameter, 
the SNA BIND command is verified for these 
values listed in Figure D-11. 
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Byte 
14 
LU-LU 
Session 
Device Format Type 
3278 *FIELD or *NOFIELD or '02'X 
*UNFORMAT or *EXTFIELD 
3284 “FIELD or *NOFIELD or '03'X 
*UNFORMAT 
3286 “FIELD or *NOFIELD or '03'X 
*UNFORMAT 
3288 *FIELD or *NOFIELD or '03'X 
*UNFORMAT 
3287 *FIELD or *NOFIELD or '03'X 
*UNFORMAT 
3287 *UNFORMAT '01'X 
3289 “FIELD or *NOFIELD or '03'X 
*UNFORMAT 
3289 *UNFORMAT '01'X 


Also, when you specify a keyboard and display 
(*3278) with formatted data for the EMLDEV 
parameter, the SNA BIND command specifies the 
screen size for the display. The value in byte 24 
determines if a default size is used or if a value in 
bytes 20 through 24 is checked for screen size. 
The sizes in Figure D-12 are supported when a 
3278 device is specified. For more information on 
the BIND command, see the book, 3270 Device 
Emulation Support. 


Figure D-12. BIND Command Screen Definition 


Byte 
24 
(*3278 


Only) Bytes 20-21 Bytes 22-23 


optional value, not 


'7TE'X '18'X '50'X 1 checked 
optional value, not 

'7F'X checked '18'X '50'X 1 
base model 2 

'02'X default 

‘00'X base default 

Note: 


1 Other possible values are: '20'X '50'X, '2B'X 
'5O'X, '1B'X '84'X 


General Considerations 


The following information for SNA 3270 support 
includes considerations for SNUF devices, 
System/36 restrictions, application identifiers, lan- 
guage operations, keywords, and system-supplied 
formats. 


SNUF Devices 


If SNUF device descriptions are to be used for the 
SNA 3270 program interface, they must be 
created on a Version 1 Release 2 Modification 0 
system or later. If you attempt to use a device 
created on an earlier release, an 82B5 return code 
is sent to your program. 


System/36 Restrictions 


Application programs running in the System/36 
environment cannot acquire a SNUF device for 
the purpose of running a SNA 3270 application. If 
a System/36 program attempts to open an ICF file 
to a SNA 3270 program interface device, an 82B4 
return code results. 


Application Identifiers 


If the host application program is the Federal 
Reserve communications application program, 
Federal Link Access for Secondary Half-sessions 
(FLASH), the application identifier (APPID) param- 
eter is checked when the BIND command is 
received from the host system. The SNUF appli- 
cation program verifies that the BIND command 
was sent from the correct application at the host 
site. This verification is done by checking the 
APPID against the user data field in the BIND 
command. lf the user data field does not exist or 
does not match the APPID, SNUF compares the 
APPID against the primary LU name in the BIND 
command. An INIT-SELF command is created 
using the APPID value as the primary LU name. 


Language Operations, Keywords, 
and System-Supplied Formats 


All data management operations supported by 
SNUF can be used with SNA 3270 program inter- 
face. The SNUF session runs in half-duplex flip- 
flop protocol. The operations listed in Figure A-1 
on page A-1 are supported. 


An application program that uses SNA 3270 
program interface to exchange 3270 data stream 
data with a host system program can be coded in 
any high-level language that can communicate 
with the host system through SNUF. See 
Appendix A for supported language operations, 
DDS keywords, and system-supplied formats. 


Example Program 


The following example ILE COBOL/400 program 
communicates with a CICS test program named 
IDO1 which runs on a host CICS system. 


An ICF file named ICF01 was created for this 
example. This example assumes that the user has 
created the SRCFILE and SRCMBR attributes. 
The program device entry created for this example 
is named CICSDEV. 


The ACQUIRE performed for this device entry 
causes a LOGON APPLID(CICS) to be sent to the 
host system. Here SNUF uses the APPID param- 
eter on the device description to build the logon 
command. This device entry is also used for any 


read. J 


J When this entry was created using the 
ADDICFDEVE command, it specified 
EMLDEV(*3278 *UNFORMAT). The 
*“UNFORMAT parameter value indicates that data 
streams will be received in an untranslated format 
and our program will be responsible for inter- 
preting the 3270 data stream. The 20-byte header 
which will be received with the data when we read 
from the host program will provide two fields for 
us. 


J Byte 1 will provide the command which has 
been extracted from the 3270 data stream and 
copied into the header for us. 


Byte 19 provides us with the data flow. In this 
example we only expect a HEX FO which tells us 
this is an LU-to-LU flow. Note the program does 
not allow for other flows that might be received. 


Eq Since BATCH(*NO) was the default, only one 
Read is necessary to receive the 3270 data 
stream from the host system which is program 
IDO1's main menu. If *YES had been specified 
multiple reads might have been necessary 
depending on the record length determined by the 
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host system. The type of 3278 is one of the valid 
3270 display types which may be used. [J 


In program APICOB1, note that 
INPUT-BUFFER redefines OUTPUT-BUFFER and 
that both records allow for a 20-byte header to 
precede the 1920 byte screen buffer which will be 
received and could be sent back to the host 
system. In APICOB1 we allow for all the header 
fields that are supported although we only expect 
two of them to be filled in for us when running in 
“UNFORMAT mode and a read is performed. 


OUTPUT-LENGTH must be provided and 
filled in when writing back to the host system. 
This length value tells the ICF file how long the 
combined header and buffer data will be. This 
length is necessary when using system-supplied 
formats such as $$SEND. 


OUTPUT-LENGTH for *UNFORMAT mode 
requires a minimum of 20 bytes. 
OUTPUT-LENGTH for other formats (*FIELD, 
*NOFIELD, *EXTFIELD) requires a minimum 
output length equal to the sum of the header plus 
the screen size. 


APICOB1 will open files ICFO1 and SHOW, 
acquire the program device CICSDEV, perform a 
main routine, close the files and exit the program. 


The MAIN-ROUTINE handles the receiving of 
the 3270 data stream and sending the clear key 
and F-11 key. The routine DSP-IN-DATA is used 
when receiving data from the host program IDO1 
to display the first 70 bytes of the data for verifica- 
tion purposes. 


When sending to CICS or responding to the 
program IDO1 note that the CLR-KEY, 
ENTER-KEY, and F11-KEY hex value is placed in 
the AID-BYTE field of DATA-3270-STRCT. 
Cursor position, if required, is placed in CURPOS 
field which follows the AID-BYTE. Compare this 
to the “FORMATTED mode where these values 
would be placed in the header. 


When this is done, the value HEX 00 is 
placed in the O-Command or byte 1 of the header. 
This is done to be consistent with the handling of 
the header when running in *FIELD or *NOFIELD 
formatted mode. 
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The value for the key entered and the 
program request value IDO1 is then placed in the 
buffer following the header and the $$SEND per- 
formed by the SEND-3270 routine. The length 
value which is set when building the output data is 
set to include the header length plus the length of 
the data in the DATA-3270-STRCT that is being 
sent to the host program. 


ICF File Creation 


The commands needed to create the descriptions 
for the SNA 3270 SUPPORT example program 
are: 


CRTLINSDLC  LIND(APILIN) RSRCNAME(LINO51) ROLE(*SEC) 


CRTCTLHOST CTLD(APICTLR) LINKTYPE(*SDLC) APPN(*NO) 


LINE(APILIN) STNADR(C1) 


CRTDEVSNUF DEVD(APIDEV) LOCADR(@7) RMTLOCNAME (APILOC) 


CTL(APICTLR) PGMSTRRQS(*NO) APPID(CICS) 4 | 
HOST(*CICS) TEXT('SNUF DEVICE FOR APICOB1') 


The ICF file ICFO1 has been created as a copy of 
the default ICF file QICDMF. The example 
program uses system supplied formats, however if 
we were using a specific format that differed from 
the system supplied one then a DDS file 
describing the format would be necessary. 


The commands needed to create the program 
device entry and the ICF file ICFO1 would look like 
this: 


CRTICFF FILE(ICFO1) SRCFILE(QDDSSRC) 
SRCMBR(ICFEXAMP) TEXT('ICF FILE FOR APICOB1 EXAMPLE') 
ADDICFDEVE  FILE(ICFO1) PGMDEV(CICSDEV) RMTLOCNAME (APILOC) 2 | 


CMNTYPE(*SNUF) DEV(APIDEV) APPID(*DEVD) HOST(*CICS) 
MSGPTC(*NO) EMLDEV(3278 *UNFORMAT) [i] [J 


The DDS for the display named SHOW which dis- 
plays input data received from the host program 
follows: 


TT Tt TTT TET TTT TT TTT TTT ETT ETT Tee eT TT Ty 
* DSPF NAME SHOW 
TT TTT TT Tt TET TIT TT TTT TTT TTT ETT T Tee TT TT Ty 
R DSP1919 LOGOUT 
Ll 70 B4 5 


Sample Program 


IDENTIFICATION DIVISION. 
PROGRAM-ID. APICOB1. 


* 
FEI IG ICI ICG ICICI ICR ICI ICICI ICICI ICICI ICI RI IR A IIR A I IK 
* USE SNUF 3270 SUPPORT TO COMMUNICATE WITH CICS USING ICF 
PROGRAM DEVICE ENTRY CICSDEV. 


THE MAIN ROUTINE WILL PERFORM THE FOLLOWING STEPS. 
APICOB1 RECEIVES THE WELCOME TO CICS SCREEN AND SENDS A 
CLEAR KEY TO THE HOST IN RESPONSE. 

APICOB1 READS IN THE BLANK SCREEN. 

APICOB1 SENDS THE PROGRAM ID IDO1 TO CICS. THIS 

RESULTS IN THE HOST PROGRAM STARTING AND SENDING A 3270 
DATA STREAM TO APICOB1. 

A READ IS PERFORMED FOR THE MAIN MENU WHICH DISPLAYS THE 
PF KEYS AND THEIR FUNCTION. 

ANOTHER READ IS ISSUED TO RECEIVE THE CHANGE DIRECTION 
INDICATOR. AFTER THIS IS RECEIVED, APICOB1 CAN THEN 
RESPOND TO THE HOST PROGRAM. 

APICOB1 SENDS A PF-11 KEY TO IDO1 WHICH WILL CAUSE 

US TO RETURN TO CICS. 

APICOB1 THEN READS IN THE BLANK SCREEN AND CLOSES FILES. 


KKEKRKKKEKRKEKKKEKEKRKERKER KER EKER ERREREREERRERREEKEREEKEREKKEEKEKERKEREEKER 


* FF FF F FF HF HF F F HF HF HF KF F 
+ + FF FH FF FH F HF F F HF F HF F HF HF FH 


* 


ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-AS400. 
OBJECT-COMPUTER. IBM-AS400. 
SPECIAL-NAMES.. 1-0-FEEDBACK IS I0-FBA 
OPEN-FEEDBACK IS OPEN-FBA 
REQUESTER IS MY-DISPLAY. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
* 
KKRKKKK KKK KEKE KR KERR EKER EKER EKER EKER EKER RRR RRR ERR RRR RRR ERR RERRRREREER 
* FILE SPECIFICATIONS * 
* * 
* ICFO1 : ICF FILE USED TO SEND/RECEIVE DATA * 
* DSPFILE : USED TO DISPLAY DATA RECEIVED FROM THE HOST* 


FIG ICI IC IOI I ICI ICI ICICI ICI ICICI I ICICI AC ICR IIR A I IR AIR Ae 
* 
SELECT ICFQ1 ASSIGN TO WORKSTATION-ICFO1-SI 
ORGANIZATION IS TRANSACTIO 
CONTROL-AREA IS TR-CTL-AREA 

FILE STATUS IS ICF-STATUS MAJ-MIN. 


SELECT SHOW ASSIGN TO WORKSTATION-SHOW 
ORGANIZATION IS TRANSACTIO 
CONTROL-AREA IS WS-CTL 

FILE STATUS IS STATUS-DSP. 


* 


DATA DIVISION. 


* 


FILE SECTION. 


* 


FD ICFO1 
LABEL RECORDS ARE STANDARD. 
* 
@1 ICF-REC. 
05 OUTPUT-BUFFER. 
10 OUTPUT-LENGTH PIc 9(04). [aq 
10 OUTPUT-HEADER. 
15 0-COMMAND PIC X(01). 
15 0-WCC PIC X(@1). 
15 0-AID PIC X(01). 
15 0-DSP PIC X(@1). 
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15 O-CURPOS. 


20 O-CURPOS-1 PIC X(@1). 

20 O-CURPOS-2 PIC X(@1). 
15 O-NUM-ENT PIC X(@2). 
15 O-NUM-LFT PIC X(@2). 
15 O-LST-ENT PIC X(@2). 
15 0-BLK-SIZ PIC X(@2). 
15 O-LINE PIC X(@1). 
15 O-RTRN-CODE PIC X(@1). 
15 O-ERR-POS PIC X(@2). 
15 0-FLOW PIC X(@1). 
15 FILLER PIC X(@1). 

10 OUTPUT-DATA PIC X(4072). 


05 INPUT-BUFFER REDEFINES OUTPUT-BUFFER. 
10 INPUT-HEADER. 


15  1-COMMAND PIc xX(01). 
15 I-WCC PIC X(01). 
15 I-AID PIC X(01). 
15 I-DSP PIC X(01). 
15 I-CURPOS. 
20 I-CURPOS-1 PIC X(01). 
20 I-CURPOS-2 PIC X(01). 
15 I-NUM-ENT PIC X(02). 
15 I-NUM-LFT PIC X(02). 
15  I-LST-ENT PIC X(02). 
15 I-BLK-SIZ PIC X(02). 
15 I-LINE PIC X(01). 
15 I-RTRN-CODE PIC X(01). 
15 I-ERR-POS PIC X(02). 
15 I-FLOW PIC X(01). 
15 FILLER PIC X(01). 
10 INPUT-DATA. 
15 LO1-IN PIC X(70). 
15 REST-OF-3270 PIC X(1850). 
15 FILLER PIC X(2156). 


FD SHOW 
LABEL RECORDS ARE OMITTED. 


01 DSP-REC. 
05 SHOW-RECORD PIC X(70). 
05 DSP1919 REDEFINES SHOW-RECORD. 
10 L1-SUB PIC X(@1) OCCURS 70 TIMES. 


* 


WORKING-STORAGE SECTION. 


* 


77 F18-KEY PIC 
77 F19-KEY PIC 


77 ICF-STATUS PIC X(@2). 
77 CONV-INDX PIC 99. 
77 STATUS-DSP PIC X(@2). 
77 HEX-40 PIC X VALUE '' ' 
77 HEX-5B PIC X VALUE '$'. 
77 HEX-61 PIC X VALUE '/'. 
77 ENTER-KEY PIC X VALUE "'" 
77 F1-KEY PIC X VALUE '1'. 
77 F2-KEY PIC X VALUE '2'. 
77 F3-KEY PIC X VALUE '3'. 
77 FA4-KEY PIC X VALUE '4'. 
77 F5-KEY PIC X VALUE '5'. 
77 F6-KEY PIC X VALUE '6'. 
77 F7-KEY PIC X VALUE '7'. 
77 F8-KEY PIC X VALUE '8'. 
77 FO-KEY PIC X VALUE '9' 
77 F1Q-KEY PIC X VALUE ':' 
77 F11-KEY PIC X VALUE '#'. 
77 F12-KEY PIC X VALUE '@'. 
77 F13-KEY PIC X VALUE 'A'. 
77 F14-KEY PIC X VALUE 'B'. 
77 F15-KEY PIC X VALUE 'C'. 
77 F16-KEY PIC X VALUE 'D'. 
77 ~F17-KEY PIC X VALUE 'E'. 

X E 

X E 
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* 


* 


* 


* 


77 F2Q-KEY PIC 
77 F21-KEY PIC 
77 F22-KEY PIC 
77 F23-KEY PIC 
77 F24-KEY PIC 
77 PAI-KEY PIC 
77 PA2-KEY PIC 
77 PA3-KEY PIC 
77 CLR-KEY PIC 
77 TST-KEY PIC 
77 NOAID-1 PIC 
77 NOAID-2 PIC 
01 TR-CTL-AREA. 
05 TR-FUNCTION-KEYS IC 
05 TR-TERMINAL-ID PIC 
05 TR-FORMAT-NAME PIC 
01 MAJ-MIN. 
05 MAJ PIC 
05 MI PIC 
01 WS-CTL. 
05 CMD-KEY PIC 
05 FILLER PIC 
05 RCD-FMT PIC 
01 DATA-3270-STRCT. 
05 AID-BYTE PIC 
05 CURPOS. 
10 CURPOS-1 PIC 
10 CURPOS-2 PIC 
05 DATA-3270 PIC 
01 HEX-00-BINARY PIC 
01 HEX-00-R REDEFINES HEX-00-BINARY. 
05 FILLER PIC 
05 HEX00 PIC 
01 HEX-11-BINARY PIC 
O01 HEX-11-R REDEFINES HEX-11-BINARY. 
05 FILLER PIC 
05 HEX-SBA PIC 
01 HEX-4A-BINARY PIC 
01 HEX-4A-R REDEFINES HEX-4A-BINARY. 
05 FILLER PIC 
05 PF22-KEY PIC 
01 HEX-6A-BINARY PIC 
01 HEX-6A-R REDEFINES HEX-6A-BINARY. 
05 FILLER PIC 
05 HEX-6A PIC 
PROCEDURE DIVISION. 
MAIN-LINE SECTION. 
MAIN-LINE-ROUTINE. 


>< >< >< >< >< >< OK OK OK OK OK OO 


xX 
X. 

xX. 

X(253). 

999 COMP-4 VALUE 00. 


X. 
X. 


999 COMP-4 VALUE 17. 


X. 
X. 


999 COMP-4 VALUE 74. 


X. 
X. 


999 COMP-4 VALUE 106. 


X. 
X. 


PERFORM OPEN-FILES THRU EXIT-OPEN-FILES. 


PERFORM 


ACQ-DEV THRU EXIT-ACQ-DEV. 


PERFORM MAIN-ROUTINE THRU EXIT-MAIN-ROUTINE. 
PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES. 
PERFORM STOP-RUN THRU EXIT-STOP-RUN. 


OPEN-FILES. 
OPEN I-0 ICFO1 
I-0 SHOW. 
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EXIT-OPEN-FILES. 
EXIT. 
* 
ACQ-DEV. 
ACQUIRE 'CICSDEV' FOR ICFO1. 
IF MAJ NOT = '00' 
THEN 
PERFORM DSP-ERR-INFO THRU EXIT-DSP-ERR-INFO 
PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES. 
EXIT-ACQ-DEV. 
EXIT. 
* 
DSP-ERR-INFO. 
DISPLAY ' MAJ/MIN ==>' MAJ-MIN. 


DISPLAY ' ICF STATUS ==>! ICF-STATUS. 
EXIT-DSP-ERR-INFO. 

EXIT. 
* 
MAIN-ROUTINE. 


PERFORM READ-RU THRU EXIT-READ-RU. 

PERFORM SEND-CLR THRU EXIT-SEND-CLR. 

PERFORM READ-RU THRU EXIT-READ-RU. 

PERFORM SEND-IDQ1 THRU EXIT-SEND-IDO1. 

PERFORM READ-RU THRU EXIT-READ-RU. 8 | 

PERFORM READ-CHG-DIR THRU EXIT-READ-CHG-DIR. 

PERFORM SEND-F11 THRU EXIT-SEND-F11. 

PERFORM READ-RU THRU EXIT-READ-RU. 
EXIT-MAIN-ROUTINE. 

EXIT. 


KKEKKEKKRKEKKEKREK KERR KEKE R EKER KER ERR RERRERERERRERERREREREKRREREEKERERKREREKERKR 


READ 3270 DATA STREAM IN 


IN THIS EXAMPLE WE CHECK THE MAJOR MINOR RETURN CODE ONLY. 
IN A PRODUCTION ENVIRONMENT THE INPUT DATA FLOW CONTROL 
FIELD WOULD BE VERIFIED ALSO. WHEN A READ IS PERFORMED IF 
ANOTHER DATA FLOW IS ENCOUNTER, SOME OTHER ACTION MAY BE 
NECESSARY. IN THIS CASE AN LU TO LU FLOW IS EXPECTED SO A 
HEX FQ WILL BE IN THE I-FLOW FIELD IN THE INPUT HEADER. 


KKEKRKEKKRKEKEKEKREKRERKEREKRRE KER KEERKEER REE REE RE ERR ERR ERREEREKRKERERKEEKEKERER 


+ + FF F F HF F 
+ + FF F F HF 


* 


READ-RU. 
MOVE SPACES TO INPUT-BUFFER. 
READ ICFQ1 TERMINAL IS 'CICSDEV'. 
IF MAJ-MIN NOT < 'Q004' 
THEN 
PERFORM DSP-ERR-INFO THRU EXIT-DSP-ERR-INFO 
PERFORM END-SESS THRU EXIT-END-SESS 
PERFORM REL-DEV THRU EXIT-REL-DEV 
PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES 
PERFORM STOP-RUN THRU EXIT-STOP-RUN. 
PERFORM DSP-IN-DATA THRU EXIT-DSP-IN-DATA. 
EXIT-READ-RU. 
EXIT. 


* 


READ-CHG-DIR. 
MOVE SPACES TO INPUT-BUFFER. 


READ ICFQ1 TERMINAL 


S 'CICSDEV'. 


IF MAJ-MIN NOT = '0300' 


THEN 
PERFORM DSP-ERR- 
PERFORM END-SESS 
PERFORM REL-DEV 17 


NFO THRU EXIT-DSP-ERR-INFO 
THRU EXIT-END-SESS 
THRU EXIT-REL-DEV 


PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES 


PERFORM STOP-RUN 
PERFORM DSP-IN-DATA 1 
EXIT-CHG-DIR. 
EXIT. 
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THRU EXIT-STOP-RUN. 
THRU EXIT-DSP-IN-DATA. 


DSP-IN-DATA. 
MOVE SPACES TO DSP-REC. 
MOVE L@1-IN TO SHOW-RECORD. 
PERFORM CONV-HEX THRU EXIT-CONV-HEX 
VARYING CONV-INDX FROM 1 BY 1 UNTIL CONV-INDX = 70. 
WRITE DSP-REC FORMAT IS 'DSP1919'. 
READ SHOW. 
EXIT-DSP-IN-DATA. 
EXIT. 
* 
CONV-HEX. 
IF L1-SUB(CONV-INDX) < ' ' 
THEN MOVE '?' TO L1-SUB(CONV-INDX) . 
EXIT-CONV-HEX. 
EXIT. 
* 
SEND-CLR. 
MOVE 21 TO OUTPUT-LENGTH. 
MOVE HEX0@ TO O-COMMAND. 
MOVE '@' TO O-FLOW. 
MOVE SPACES TO OUTPUT-DATA, DATA-3270-STRCT. 
MOVE CLR-KEY TO AID-BYTE. 
MOVE ' ' TO CURPOS. 
PERFORM SEND-3270 THRU EXIT-SEND-3270. 
EXIT-SEND-CLR. 
EXIT. 
* 
SEND-ID@1. 
MOVE 27 TO OUTPUT-LENGTH. 
MOVE HEX0@ TO O-COMMAND. 
MOVE '@' TO O-FLOW. 
MOVE SPACES TO OUTPUT-DATA, DATA-3270-STRCT 
MOVE ENTER-KEY TO AID-BYTE. 
MOVE ' D' TO CURPOS. 
MOVE 'IDO1' TO DATA-3270. 
PERFORM SEND-3270 THRU EXIT-SEND-3270. 
EXIT-SEND-IDO1. 
EXIT. 
* 
SEND-F11. 
MOVE 23 TO OUTPUT-LENGTH. 
MOVE HEX0@ TO O-COMMAND. 
MOVE '@' TO O-FLOW. 
MOVE SPACES TO OUTPUT-DATA, DATA-3270-STRCT. 
MOVE F11-KEY TO AID-BYTE. 
MOVE SPACES TO CURPOS. 
PERFORM SEND-3270 THRU EXIT-SEND-3270. 
EXIT-SEND-F11. 
EXIT. 
* 
SEND-3270. 
MOVE DATA-3270-STRCT TO OUTPUT-DATA. 
WRITE ICF-REC FORMAT IS '$$SEND'. 
IF MAJ-MIN NOT = '0000' 
THEN 
PERFORM DSP-ERR-INFO THRU EXIT-DSP-ERR-INFO 
PERFORM END-SESS THRU EXIT-END-SESS 
PERFORM REL-DEV THRU EXIT-REL-DEV 
PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES 
PERFORM STOP-RUN THRU EXIT-STOP-RUN. 
EXIT-SEND-3270. 
EXIT. 
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REL-DEV. 
MOVE ZEROS TO OUTPUT-LENGTH. 
WRITE ICF-REC FORMAT IS '$$SENDET'. 
IF MAJ-MIN NOT = '0000! 
THEN 
PERFORM DSP-ERR-INFO THRU EXIT-DSP-ERR-INFO 
PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES 
PERFORM STOP-RUN THRU EXIT-STOP-RUN. 
EXIT-REL-DEV. 
EXIT. 
* 
END-SESS. 
WRITE ICF-REC FORMAT IS '$$E0S'. 
IF MAJ-MIN NOT = '0000! 
THEN 
PERFORM DSP-ERR-INFO THRU EXIT-DSP-ERR-INFO 
PERFORM REL-DEV THRU EXIT-REL-DEV 
PERFORM CLOSE-FILES THRU EXIT-CLOSE-FILES 
PERFORM STOP-RUN THRU EXIT-STOP-RUN. 
EXIT-END-SESS. 
EXIT. 
* 
CLOSE-FILES. 
DISPLAY 'CLOSING FILES’. 
CLOSE ICFO1. 


CLOSE SHOW. 

EXIT-CLOSE-FILES. 
EXIT. 

* 

STOP-RUN. 
STOP RUN. 

EXIT-STOP-RUN. 
EXIT. 
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Program Examples 


This appendix contains two examples of an item-inquiry application. The applica- 
tion consists of Program A, which is the AS/400 program, and Program B, which is 
the program for the remote host system. For an SNA 3270 program example, see 
Appendix D. 


“Example 1: AS/400 System to System/370 System (CICS/VS)” on page E-2 illus- 
trates communications programming between the AS/400 system and a 
System/370 system operating under CICS/VS. Program A is a ILE COBOL/400 
program with system-supplied formats; Program B is a System/370 COBOL 
CICS/VS program. 


“Example 2: AS/400 System to System/370 System (IMS/VS)” on page E-17 illus- 
trates communications programming between the AS/400 system and a 
System/370 system operating under IMS/VS. Program A is an ILE RPG/400 
program with data description specifications (DDS); Program B is a System/370 
COBOL IMS/VS program. 


“Example 3: AS/400 System to System/370 System (CICS/VS)” on page E-27 
illustrates communications programming between the AS/400 system and a 
System/370 system operating under CICS/VS. Program A is a ILE C/400 program 
with system-supplied formats; Program A is a System/370 COBOL CICS/VS 
program. 


Before running the program examples, create a line description, a controller 
description, and device descriptions on the AS/400 system. Sample commands 
follow: 


CRTLINSDLC 
LIND(XLINE) 
RSRCNAME (LINO11) 
ROLE (*SEC) 


CRTCTLHOST 
CTLD(XCTLR) 
LINKTYPE(*SDLC) 
APPN(*NO) 
LINE(XLINE) 
STNADR(C1) 


CRTDEVSNUF 

DEVD(XDEV) 

LOCADR (06) 
RMTLOCNAME (CICSLOC) 
CTL(XCTLR) 
PGMSTRRQS (*NO) 
APPID(CICS) 

HOST (*CICS) 


CRIDEVSNUF 
DEVD(YDEV) 
LOCADR (0A) 
RMTLOCNAME ( IMSLOC) 
CTL(XCTLR) 
PGMSTRRQS (*NO) 
APPID(XAIMS) 
HOST (*IMS) 


E-1 


The item-inquiry application for both “Example 1: AS/400 System to System/370 
System (CICS/VS)” and “Example 2: AS/400 System to System/370 System 
(IMS/VS)” is shown in Figure E-1. 


(_)) 
J 
AS/400 System _— System/370 System 
ae > 
es an ——|--+|  cicswstaskor 
Application ianti 
IMS/VS Application 
FileA [j> Program A fa FileB Program B (i 
v 
7 — | , 
ICF 
Data CICS/VS or IMS/VS 
Management 
4 pee 8 
SNUF Access Method 


RSLS173-2 


Figure E-1. Item-Inquiry Application 


In Figure E-1: 


e Application Program A (in the AS/400 system) shows a prompt asking an oper- 
ator to enter an item number requesting information about the item iq. 


e¢ When the operator enters the item number, Program A reads the number and 
searches File A (the local file) for the item ,]. 


e If the item is found in the local file, Program A shows information about the 
item qj. 

e lf the item is not found on the local file, Program A uses SNUF to send the item 
number to the host system [J and QJ. 


e Program B (in the host system) uses the item number to search the remote file 
for the item [¥. 


e lf the item is found in the remote file, Program B sends information about the 
item to Program A and |]. If the item is not found in the remote file, 
Program B sends the characters **~. 


e lf Program A receives information about the item, it shows that information. If it 
receives the characters ***, it shows the message ITEM NUMBER NOT FOUND fg. 


Example 1: AS/400 System to System/370 System (CICS/VS) 


The following example consists of an AS/400 COBOL program with system- 
supplied formats, talking to a System/370 COBOL CICS/VS program. 


Not all programming considerations or techniques are illustrated in this example. 
You should review the example before you begin application design and coding. 
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ILE COBOL/400 Program for the AS/400 System (Program A) 
The following program (PROGACOB) is used on the AS/400 system. 


When PROGACOB is called, a display is presented. This display contains a single 
inquiry line that is 23 bytes long. Type an item number on the inquiry line and 
press the Enter key to begin searching. The local database (FILEA) is searched, 
and if a matching item is found, up to four item quantities are displayed. 


If a matching item number is not in the local file, then a request is built and sent to 
the host system. The program, ICII, is started to obtain the matching item number 
and quantities from the remote system database; the matching item number and its 
associated quantities are returned to PROGACOB, which displays the quantities 
that are available. 


DDS Source: The DDS source for DISPFILE is illustrated in Figure E-2. The 
other files are either program-described (FILEA and PRINTFILE) or default 
(QICDMF) and, therefore, require no DDS. 


[RR KKR KKK EKER ER EKER ERE KKEKR ERE KEK KERR ER EKER ERK ER EKER ERE RR EKER EKER 


A* * 

Ax LOCAL DISPLAY FILE * 

A* * 

ARR AK KK KKK KKK KKK KAKA KE RRR R EKER KERR KKK ERE RRR EERE KEKE EKA ERER ERE 

A* 

A CAO1 

A CA07 

A R WSFILEIN 

A ITMNUM 23 I 2 10 

A 01 O 4 10'INVALID ITEM NUMBER ENTERED' 
A 02 O 4 10'ITEM NUMBER NOT FOUND' 

A 0 12 10'PRESS CMD KEY 7 TO TERMINATE' 
A R WSFILEOT 

A ITMNUM 23 0 2 10 

A QTY1 6 00 4 12 

A QTY2 6 00 5 12 

A QTY3 6 00 6 12 

A QTY4 6 00 7 12 

A MSG 80 O 8 10 

A RETCOD 4 010 10 

A REASON 30 011 10 

A FILLER 95 0 12 10 

A 0 14 10'PRESS CMD KEY 7 TO TERMINATE OR' 
A 0 15 10'CMD KEY 1 FOR ANOTHER INQUIRY' 


Figure E-2. DDS Source for DISPFILE 


Program Device Entry Definition: The command needed to define the program 
device entry is: 


ADDICFDEVE FILE(*LIBL/QICDMF) 
PGMDEV (SNUFDEVICE) 
RMTLOCNAME (CICSLOC) 
CMNTYPE(*SNUF) 
DEV (XDEV) 
APPID(CICS) 
HOST(*DEVD) or (*CICS) 
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ILE COBOL/400 Program: Figure E-3 shows the ILE COBOL/400 program 


PROGACOB for the AS/400 system. 


KKEKRKEKKEKEKKEEKKEKER KER REERE RRR REE RREREEREREREREREEKEREKREKREREERERERKEKEREERE 


* * 
* PROGACOB - ITEM INQUIRY WRITTEN IN COBOL * 
* * 


FOO IORI GIGI GIO IO GIG GIGI OIC ICICI III CR IR AIK 
* 
IDENTIFICATION DIVISION. 
* 
FAIS G IOI GOI IOI IGG IG ICICI ICICI II ICICI ICR A I 


* * 
* PROGACOB - ITEM INQUIRY WRITTEN IN COBOL * 
* * 


KKEKRKEKKEKREKERKERKEKREKERKEER REE EKER EREREREEEREREREREKEKEREKERKKEKKERKE 


PROGRAM-ID. PROGACOB. 
ENVIRONMENT DIVISION. 
* 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-AS400. 
OBJECT-COMPUTER. IBM-AS400. 
* 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT QICDMF 
ASSIGN TO WORKSTATION-QICDMF-SI 
ORGANIZATION IS TRANSACTION 
FILE STATUS IS STATUS-IND MAJ-MIN 
CONTROL-AREA IS COMM-CONTROL-AREA. 


SELECT DISPFILE 
ASSIGN TO WORKSTATION-DISPFILE 
ORGANIZATION IS TRANSACTION 
FILE STATUS IS WS-FS 
CONTROL-AREA IS WS-CONTROL-AREA. 


SELECT FILEA ASSIGN TO DISK-FILEA 
ORGANIZATION IS INDEXED 
ACCESS IS RANDOM 
RECORD KEY IS FILEA-NUMBER. 


SELECT PRINTFILE ASSIGN TO PRINTER-PRINTFILE. 


DATA DIVISION. 
FILE SECTION. 


FD QICDMF 
LABEL RECORDS ARE OMITTED. 
01 COMMREC. 

05 COMMUNICATION-RECORD PIC X(256). 
FD DISPFILE, LABEL RECORDS ARE OMITTED. 
01 DISPREC. 

03 ITEM-NUMBER PIC X(23). 
03 QTY-1 PIC 9(6). 
03 QTY-2 PIC 9(6). 
03 QTY-3 PIC 9(6). 
03 QTY-4 PIC 9(6). 
03 MSG PIC X(80). 
03 RETURN-CODE PIC X(4). 
03 REASON-WHY PIC X(30). 
03 FILL1 PIC X(95). 


* 


Figure E-3 (Part 1 of 6). COBOL Program A for the AS/400 System 
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FD FILEA, LABEL RECORDS ARE STANDARD. 


01 FILEAREC. 

03 FILEA-RECORD. 
FILEA-NUMBER 
FILLER 
FILEA-QTY-1 
FILEA-QTY-2 
FILEA-QTY-3 
FILEA-QTY-4 


* 


u,v, VT, UU 


C X(23). 
C X(3). 
C 9(6). 
C 9(6). 
C 9(6). 
IC 9(6). 


FD PRINTFILE, LABEL RECORDS ARE OMITTED. 


01 PRINT-RECORD PIC X(132). 
* 
WORKING-STORAGE SECTION. 
77 ICF-SESSION PIC X(10) VALUE "SNUFDEVICE". 
77 SAVE-ITEM-NUMBER PIC X(23). 
77 STATUS-IND PIC X(2). 
77 WS-FS PIC X(2). 
3 
01 COMM-CONTROL-AREA. 
03 FILLER PIC X(2). 
03 PGM-DEV-NAME PIC X(10). 
03 RCD-FMT-NAME PIC X(10). 
* 
01 WS-CONTROL-AREA. 
03 CMD-KEY PIC X(2). 
88 CMD-KEY-1 VALUE "01". 
88 CMD-KEY-7 VALUE "07". 
03 FILLER PIC X(10). 
03 RCD-FMT PIC X(10). 
* 
01 SCREEN-INDICATORS. 
03 101 PIC 1 VALUE ZERO, INDICATOR 01. 
03 102 PIC 1 VALUE ZERO, INDICATOR 02. 
03 103 PIC 1 VALUE ZERO, INDICATOR 03. 
* 
01 ACQUIRE-INDICATOR. 
03 104 PIC 1 VALUE ZERO, INDICATOR 01. 
* 
01 EVOKE-RECORD. 
03 PROCEDURE-NAME PIC X(8) VALUE "ICII ". 
03 PASSWORD PIC X(8). 
03 USER-ID PIC X(8). 
03 LIBRARY-NAME PIC X(8). 
03 FILLER PIC X(20). 
03 DATA-LENGTH PIC X(4) VALUE "0023". 
03 ICF-ITEM-NUMBER-OUT PIC X(23). 
* 
01 ICF-RECORD-IN. 
03 ICF-RECORD-CHECK. 
05 FIRST-3-CHARACTERS PIC X(3). 
05 REST-OF-DATA PIC X(253). 
* 
03 ICF-RECORD-OK REDEFINES ICF-RECORD-CHECK. 
05 FILLER PIC X(32). 
05 ICF-ITEM-NUMBER-IN PIC X(23). 
05 FILLER PIC X(145). 
05 ICF-QTY-1 PIC 9(6). 
05 ICF-QTY-2 PIC 9(6). 
05 ICF-QTY-3 PIC 9(6). 
05 ICF-QTY-4 PIC 9(6). 
05 FILLER PIC X(32). 


* 


Figure E-3 (Part 2 of 6). COBOL Program A for the AS/400 System 
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01 ICF-RECORD-OUT. 


03 RECORD-LENGTH PIC 9(4). 
03 THE-RECORD PIC X(256). 
* 
01 MAJ-MIN. 
03 MAJOR-RETURN-CODE PIC X(2). 
03 MINOR-RETURN-CODE PIC X(2). 
* 
01 PRINT-CODES. 
03 FILLER PIC X(14) VALUE "RETURN CODE ". 
03 PRINT-RETURN-CODE PIC X(4). 
03 FILLER PIC X(11) VALUE " OPCODE IS ". 
03 OPCODE PIC X(6). 
03 FILLER PIC X(11) VALUE " DATA SENT ". 
03 PRINT-ITEM-NUMBER PIC X(23). 


* 


PROCEDURE DIVISION. 


* 


KKEKKEKKEKEKEKKEEKRERKER ER EKER EER EEE REE RE EREERRERREKRRERERREEKEREKREKERER 


* * 

* INITIALIZATION * 

* * 

FOO GIO GIO IO GG IGG OIC IOI ICICI I ICR IR A I 
OPEN-FILES. 


OPEN I-O DISPFILE, QICDMF. 

OPEN OUTPUT PRINTFILE. 

OPEN INPUT FILEA. 

MOVE B"O" TO 101, 102, 103, 104. 
MOVE SPACES TO DISPREC. 


* 
KKEKRKEKKEKEKEKREKEKKER KEKE RERREER EERE REE REEREERREEKEREREREEKRKEEKEREKERKERER 


* * 
* DISPLAY SCREEN REQUESTING ITEM NUMBER. IF CMD 7, * 
* GO TO CLOSE FILES. SET UP INDICATORS TO DISPLAY * 
* ERRORS IF ITEM NUMBER IS SPACE OR ZEROS * 
* * 


KKEKKEKKEKEKKKRKEKKEKKER EKER KER REER ERE REE RE EREEEREREREERERERERERKEKRKEKERKE 
ITEM-INQUIRY. 
IF 103 = B"1" 
MOVE B"0" TO 103 
WRITE DISPREC 
FORMAT IS "WSFILEOT" 
READ DISPFILE 
INDICATORS ARE SCREEN-INDICATORS 
IF CMD-KEY-7 
GO TO CLOSE-FILES. 
* MUST BE CMD-KEY-1 
WRITE DISPREC 
FORMAT IS "WSFILEIN" 
INDICATORS ARE SCREEN-INDICATORS. 
READ DISPFILE 
FORMAT IS "WSFILEIN". 
MOVE B"O" TO 101, 102, 103. 
IF CMD-KEY-7 
GO TO CLOSE-FILES. 
IF ITEM-NUMBER = SPACES OR ITEM-NUMBER = ZEROS 
MOVE B"1" TO 101 
GO TO ITEM-INQUIRY. 


Figure E-3 (Part 3 of 6). COBOL Program A for the AS/400 System 
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* 


KKEKRKEKKEKRKEKKEKEKKEKEKEKEKKER KER KEKER EKER REE REERRERREEKEREKEEREREKEKEKEKERERER 


READ LOCAL FILE 'FILEA' FOR REQUESTED ITEM NUMBER. 
IF ITEM IS FOUND LOCALLY, DISPLAY ITEM INFORMATION. 
IF ITEM IS NOT FOUND LOCALLY, INQUIRE OF 'ITEMBCOB' 
USING ICF. 


+ + FF F 
+ + F F F 


FEI GIO ICICI ICI I IC ICICI ICICI ICICI ICICI ICR IIR AI IR A IR AOE 
READ-FILEA-FILE. 
OVE SPACES TO FILEA-RECORD. 
OVE ITEM-NUMBER TO FILEA-NUMBER. 
READ FILEA, 

INVALID KEY 

GO TO ICF. 

OVE FILEA-QTY-1 TO QTY-1. 
OVE FILEA-QTY-2 TO QTY-2. 
OVE FILEA-QTY-3 TO QTY-3. 
OVE FILEA-QTY-4 TO QTY-4. 
GO TO ITEM-INQUIRY. 


* 


KKEKRKEKKEKREKEKEEKKEKEKERKEKREREREKERE REE REREREEREERRERREREKEREEKEREKKEEKKEKRKERER 


* * 
* ACQUIRE ICF-SESSION (SNUFDEVICE), IF NOT ACQUIRED. * 
* * 


FIO GI ICICI IOI ICI ICI III ICICI ICICI ICICI RIOR IIR A IIR A ICR AOE 
ICF. 
IF 104 = B"0" 
MOVE B"1" TO 104 
ACQUIRE ICF-SESSION FOR QICDMF 
MOVE "ACQ" TO OPCODE 
PERFORM CHECK-RETURN-CODE THRU CHECK-RETURN-CODE-END 
IF 103 = B"1" 
GO TO ITEM-INQUIRY. 
* 


KKEKRKEKKEKRKEKKEKEKKEKEKEKEKKER KER REE REE REREREERRERREEREEKEREEKEREKEEKEKERER 


* * 
* EVOKE 'ICII' AT HOST. * 
* * 


FIGS ICI ICI IO ICI I IC ICICI ICICI ICICI ICICI RIOR IIR AI IR A IK AE 
MOVE ITEM-NUMBER TO ICF-ITEM-NUMBER-OUT. 
WRITE COMMREC FROM EVOKE-RECORD 
FORMAT IS "$$EVOK". 
MOVE "EVOK" TO OPCODE. 
PERFORM CHECK-RETURN-CODE THRU CHECK-RETURN-CODE-END. 
IF 103 = B"1" 
PERFORM SEND-EOS 
GO TO ITEM-INQUIRY. 


* 


Figure E-3 (Part 4 of 6). COBOL Program A for the AS/400 System 
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KKEKKEKKEKRKEKKEEKRKEKEKER KERR KER REE REE ERE REEREERREKERERREREKREEKEREKREKKERER 


* * 
* GET INPUT FROM HOST. * 
* * 


FIG IO ICI ICI IOI I ICI ICICI ICICI ICICI TCI IR IIR RI IR A I IK AOE 
MOVE SPACES TO ICF-RECORD-IN. 
READ QICDMF RECORD INTO ICF-RECORD-IN. 
MOVE "GET" TO OPCODE. 
PERFORM CHECK-RETURN-CODE THRU CHECK-RETURN-CODE-END. 
IF 103 = B"1" 
PERFORM SEND-EOS 
GO TO ITEM-INQUIRY. 


* 


KKEKKEKKEKRKEKKEEKKEKEKRKEKERRER EER ERRERERERREEREERERERRERREREREEKEREKRERERER 


* * 
* SEND END OF TRANSACTION. * 
* * 


FEI IOI ICG ICI ICR IC ICICI ICICI ICICI I ICICI ICI IR I IR RI IR A IIR A 
MOVE SPACES TO DISPREC. 
MOVE @ TO RECORD-LENGTH. 
WRITE COMMREC FROM ICF-RECORD-OUT 
FORMAT IS "$$SENDET". 
MOVE "SENDET" TO OPCODE. 
PERFORM CHECK-RETURN-CODE THRU CHECK-RETURN-CODE-END. 
IF 103 = B"1" 
PERFORM SEND-EOS 
GO TO ITEM-INQUIRY. 


* 


KKEKREKKERKEKRKERKRKEKKE KER KER RER ERE REE RR EREERERERREKEKREEKEREKKREKERERER 


CHECK FOR ERROR MESSAGE (3 ASTERISKS). 

IF ITEM NUMBER IS NOT FOUND, DISPLAY MESSAGE ‘ITEM 
NUMBER NOT FOUND' TO THE SCREEN. 

IF THE ITEM IS FOUND, DISPLAY THE INVENTORY INFOR. 


a A 
+ + F F HF 


FEI IIR ICI ICICI IO ICICI ICICI ICICI ICICI ICI IR IIR RI IR A IIR AOE 
MOVE B"O" TO I01, 102, 103. 
MOVE ITEM-NUMBER TO SAVE-ITEM-NUMBER. 
MOVE SPACES TO DISPREC. 
IF FIRST-3-CHARACTERS = "xxx" 
MOVE B"1" TO 102 
ELSE 
MOVE B"1" TO 103 
MOVE ICF-ITEM-NUMBER-IN TO ITEM-NUMBER 
MOVE ICF-QTY-1 TO QTY-1 
MOVE ICF-QTY-2 TO QTY-2 
MOVE ICF-QTY-3 TO QTY-3 
MOVE ICF-QTY-4 TO QTY-4. 
GO TO ITEM-INQUIRY. 


Figure E-3 (Part 5 of 6). COBOL Program A for the AS/400 System 
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C4 
KRKKKKR KKK EKER KKK KEK RE RRR KERR RRR KERR RRR RRR RRR ERR RRR EKRRRERREER 
* * 
* CLOSE FILES AND END JOB. * 
= * 
KKRKKKKRKKR EKER KERR KERR ERR RK RRR RRR RRR RRR RRR RRR EKER ERR RRERRREER 
CLOSE-FILES. 
CLOSE QICDMF, DISPFILE, FILEA, PRINTFILE. 
STOP RUN. 
* 
SEND-EOS. 
MOVE B"O" TO 104. 
MOVE SPACES TO DISPREC. 
WRITE COMMREC 
FORMAT IS "$$E0S". 
MOVE "EOS" TO OPCODE. 
MOVE MAJ-MIN TO PRINT-RETURN-CODE. 
WRITE PRINT-RECORD FROM PRINT-CODES 
AFTER ADVANCING 2 LINES. 


* 
KKERKEKKEREKRERKRKEKRKEKRER KER RERERERERERREREEEREREREKEREREKEREKREEKKEKKEEKE 


* * 
* CHECK RETURN CODE. * 
* * 


FIG ICI ICICI III ICICI IC ICICI ICICI ICICI IIR AIC IR AIK AOE 
CHECK-RETURN-CODE. 
IF MAJOR-RETURN-CODE < "04" 
GO TO CHECK-RETURN-CODE-END. 


MOVE ITEM-NUMBER TO PRINT-ITEM-NUMBER. 
MOVE MAJ-MIN TO PRINT-RETURN-CODE. 
WRITE PRINT-RECORD FROM PRINT-CODES 
AFTER ADVANCING 2 LINES. 
MOVE SPACES TO RETURN-CODE. 
IF MAJOR-RETURN-CODE = "04" 
OVE MAJ-MIN TO RETURN-CODE 
OVE "OUTPUT EXCEPTION" TO REASON-WHY 
READ QICDMF RECORD INTO ICF-RECORD-CHECK 
OVE ICF-RECORD-CHECK TO MSG 
OVE B"1" TO 103 


ELSE 
IF MAJOR-RETURN-CODE = "82" 

OVE MAJ-MIN TO RETURN-CODE 

OVE "UNABLE TO ACQUIRE" TO REASON-WHY 

OVE B"1" TO 103 

OVE B"O" TO 104 

ELSE 

IF MAJOR-RETURN-CODE > "04" 

OVE MAJ-MIN TO RETURN-CODE 

OVE B"1" TO 103. 

CHECK-RETURN-CODE-END. 


Figure E-3 (Part 6 of 6). COBOL Program A for the AS/400 System 
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CICS/VS Program Used by the Host System (Program B) 


The program in Figure E-4 is used by the host system to communicate with the 
AS/400 system. 


MEMBER NE ICII 
IDENTIFICATION DIVISION. 
SKIP3 
FEI GI ICI ICICI I IO ICICI ICICI ICI ICICI RICCI I IIR AI IR A I IR Ae 
* * 
* ICII INVENTORY INQUIRY * 
* * 
FIORE IC III ICI ICG ICICI ICICI ICICI RICCI I IIR AI IR A I IK Ae 
SKIP3 
PROGRAM-ID. ICII. 
SKIP1 
SKIP3 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SKIP1 


SOURCE-COMPUTER. IBM-370-155. 
OBJECT-COMPUTER. IBM-370-155. 


EJECT 
DATA DIVISION. 
SKIP3 
WORKING-STORAGE SECTION. 
SKIP1 
77 FUNCTION PIC X(4). 
77 PSB-NAME PIC X(8) VALUE 'MSCTGOOS'. 
77 NORESP PIC X(1) VALUE LOW-VALUES. 
77 PCBOK PIC X(2) VALUE SPACES. 
77 TDI-LENGTH PIC $9(4) COMP VALUE +256. 
77 TDO-LENGTH PIC $9(4) COMP VALUE +256. 
77 ABEND-CODE PIC X(4) VALUE SPACES. 
EJECT 
KRKKKKKKEK EKER KEKE KR EKER ERR EKER RRR RRR RRR RRR RRR RRR RRR RKER RRR RKERER 
* * 
* TRANSACTION DATA RECEIVED FROM IBM AS/400 SYSTEM * 
* * 
KRKEKKKRKEKR KEKE KR RRR ERR KERR RRR RK RRR RRR EKER ERR RRR RRR RKERREREER 
SKIP1 
01 TRANS-DATA-IN. 
05 TDI-PGMID PIC X(4). 
05 TDI-FILL1 PIC X(1). 
05 TDI-MSINITEM PIC X(23). 
SKIP3 
KRKEKKR KKK EKER KER ERR ERR RRR RRR RRR RRR ERR RRR ERR RRR RRERERRRRREER 
* * 
* TRANSACTION DATA SENT BACK TO IBM AS/400 SYSTEM * 
* * 
KRKKKKKEKKR EKER KERR ERR RRR EKER KERR RRR ERR ERR RRR RRR RRR RRR RERERREKREREER 
SKIP1 
01 TRANS-DATA-OUT. 
05 TDO-FILL1 PIC X(2) VALUE SPACES. 
05 TDO-FILLX PIC X(30) VALUE SPACES. 
05 TDO-MSINITEM PIC X(23). 
05 TDO-FILL2 PIC X(145) VALUE SPACES. 
05 TDO-MSLCHAND1 PIC $9(6). 
05 TDO-MSLCHAND2 PIC $9(6). 
05 TDO-MSLCHAND3 PIC S9(6). 
05 TDO-MSLCHAND4 PIC $9(6). 


Figure E-4 (Part 1 of 7). CICS/VS Program Used by the Host System 
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MEMBER NE ICII 


05 TDO-FILL3 PIC X(32) VALUE SPACES. 

SKIP3 
01 ERROR-MESSAGE REDEFINES TRANS-DATA-OUT. 

05 EM-MESSAGE PIC X(51). 

05 EM-FILLER PIC X(205). 

EJECT 
FIG ICICI IOI ICI I IC ICICI I IC ICICI ICI RIOR IIR A IIR A I IK HE 
* * 
* DL/I INVENTORY DATABASE SEGMENT INPUT AREA * 
* * 


KKEKRKEKKEKREKKERKREKREKRERKEERRER ERE REE REERREEKEREKREEKEREKEKEREREEKEKRERER 


SKIP1 
01 SEGMENT-MSININO1-IN. 

05 MSINITEM PIC X(23). 

05 MSINBCOD PIC X(2). 

05 MSINCOST PIC S9(7) COMP-3. 

05 MSINDESC PIC X(10). 

SKIP3 
01 SEGMENT-MSLCINO1-IN. 

05 MSLCLOCD PIC X(2). 

05 MSLCHAND PIC $9(9) COMP-3. 

05 MSLCALOC PIC $9(9) COMP-3. 

05 MSLCCLOC PIC $9(9) COMP-3. 

05 MSLCBORD PIC $9(9) COMP-3. 

05 MSLCWORK PIC $9(9) COMP-3. 

EJECT 
FEI IG ICI IC ICICI IC ICICI ICICI ICICI RIC IR IIR A IIR A I IK AE 
* * 
* DL/I INVTY DATABASE SEGMENT SEARCH ARGUMENTS (SSA'S) * 
* * 


KKEKRKEKKEKRKEKKEKEKRKEKEREKKERKEEREREREREREREREERREEKRRERREEKEREREKRREEKKEEKEKERER 


SKIP1 
01 INVTY-SEGMENT-SSA. 
05 FILLER PIC X(19) | VALUE 'MSININO1(MSINITEM ='. 
05 SSA-MSINITEM PIC X(23). 
05 FILLER PIC X(1) “VALUE ')'. 
SKIP3 
01 QTYS-SEGMENT-SSA. 
05 FILLER PIC X(9) VALUE 'MSLCINO1 '. 
EJECT 
KKRKEKKKRKEKR KERR KEK REE RRR KERR KERR RRR KERR RR ERR RRR RRR RRR RKERERRRREREER 
* * 
* MISCELLANEOUS WORKING-STORAGE AREAS. * 
* * 


KKEKRKEKKEKRKEKKEKEKREKEKERKERKEERKEKERE REE REREREEREREREEREREKEREREEKEREKERERER 


SKIP1 

01 DLI-FUNCTIONS. 
05 GU PIC X(4) VALUE 'GU '. 
05 GNP PIC X(4) VALUE 'GNP '. 
05 PCB PIC X(4) VALUE 'PCB '. 
05 TERM PIC X(4) VALUE 'TERM'. 
SKIP3 


Figure E-4 (Part 2 of 7). CICS/VS Program Used by the Host System 
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01 MSG-NOT-FOUND. 


05 FILLER PIC X(11) VALUE '***ERROR***'. 
05 FILLER PIC X(6) VALUE ' ITEM '. 
05 MSG-MSINITEM PIC X(23). 
05 FILLER PIC X(11) VALUE ' NOT FOUND.'. 
SKIP3 
01 DLI-SWITCH PIC 9 VALUE 0. 
88 QTYS-OK VALUE 0. 
88 QTYS-UIB-ERROR VALUE 1. 
EJECT 
LINKAGE SECTION. 
SKIP1 
01 BLL-CELLS. 
05 FILLER PIC 9(8) COMP. 


05 DLI-UIB-PTR PIC 9(8) COMP. 
05 DLI-PCB-PTRS PIC 9(8) COMP. 
05 PCB1-PTR. 
10 FILLER PIC 9(8) COMP. 
EJECT 
COPY DLIUIB. 
SKIP3 
01 PCB-PTRS. 
05 B-PCB1-PTR PIC S9(8) COMP. 
SKIP3 
01 PCB1. 
@5 PCB1-DBD-NAME PIC X(8). 
@5 PCB1-SEG-LEVEL PIC X(2). 
05 PCB1-STATUS PIC X(2). 
88 INVENTORY-SEGMENT-FOUND VALUE ' '. 
88 END-OF-CHAIN VALUE 'GE'. 
88 INVENTORY-DOESNT-EXIST VALUE 'GE'. 
88 QUANTITY-SEGMENT~-FOUND VALUE ' '. 
@5 PCB1-PROC-OPTN PIC X(1). 
05 PCB1-FILL1 PIC $9(5) COMP. 
@5 PCB1-SEG-NAME PIC X(8). 
@5 PCB1-LENG-KFBA PIC S9(5) COMP. 
@5 PCB1-NUMBOSSEG PIC S9(5) COMP. 
05 PCB1-KEY-FBA PIC X(256). 


EJECT 
FEI II I IC ICI IC IOI I ICI ICICI ICICI ICICI ICI IR IIR A IIR A I IK AOE 
* * 
* MAIN LINE ROUTINE. * 
* * 
FEI IORI II ICI ICI IOI ICICI ICICI ICICI ICI IR ICI RR I IRR IIR A IK AOE 
SKIP1 
PROCEDURE DIVISION. 
SKIP1 


PERFORM GET-PSB. 
IF PCB1-DBD-NAME = 'MSDPINQ1' 
PERFORM GET-PSB. 
MOVE TDI-MSINITEM TO TDO-MSINITEM, SSA-MSINITEM 
PERFORM GET-INVTY 
IF INVENTORY -SEGMENT -FOUND 
PERFORM GET-QTYS-ON-HAND THRU GET-QTYS-EXIT 
IF QTYS-OK 
PERFORM SEND-DATA 
ELSE 
MOVE 'QTYU' TO ABEND-CODE 
PERFORM CICS-ABEND 


Figure E-4 (Part 3 of 7). CICS/VS Program Used by the Host System 
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ELSE 
IF INVENTORY-DOESNT-EXIST 
MOVE TDI-MSINITEM TO MSG-MSINITEM 
MOVE SPACES TO EM-FILLER 
MOVE MSG-NOT-FOUND TO EM-MESSAGE 
PERFORM SEND-DATA 
ELSE 
MOVE 'ITYP' TO ABEND-CODE 
PERFORM CICS-ABEND 
ELSE 
MOVE 'INVD' TO ABEND-CODE 
PERFORM CICS-ABEND. 
SKIP3 
PERFORM RELEASE-PSB. 
SKIP1 
EXEC CICS RETURN END-EXEC. 
SKIP1 
GOBACK. 
EJECT 


KKEKRKEKKERKEKKEEKKEKKERKER KER ERE REE EREREERREERRERREREKEREEKEREKERKKEKERER 


* * 
* CLOSED SUBROUTINES. * 
* * 
FEI IG ICICI ICICI ICG ICI I IC ICICI ICICI IOI I IIR A IIR AIK A 


SKIP1 
GET-PSB. 
SKIP1 
MOVE PCB TO FUNCTION. 
CALL 'CBLTDLI' USING FUNCTION, PSB-NAME, DLI-UIB-PTR. 
IF UIBFCTR = NORESP 
MOVE UIBPCHAL TO DLI-PCB-PTRS 
MOVE B-PCB1-PTR TO PCB1-PTR 
ELSE 
MOVE 'PSBU' TO ABEND-CODE 
PERFORM CICS-ABEND. 
SKIP2 
READ-TERMINAL. 
SKIP1 
EXEC CICS 
RECEIVE INTO(TRANS-DATA-IN) 
LENGTH (TDI-LENGTH) 
END-EXEC. 
SKIP2 
SEND-DATA. 
SKIP1 
EXEC CICS 
SEND FROM(TRANS-DATA-OUT) 
LENGTH (TDO-LENGTH) 
END-EXEC. 
SKIP3 
RELEASE-PSB. 
SKIP1 
MOVE TERM TO FUNCTION. 
CALL 'CBLTDLI' USING FUNCTION. 
EJECT 


Figure E-4 (Part 4 of 7). CICS/VS Program Used by the Host System 
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READ-TERMINAL. 
SKIP1 
EXEC CICS 
RECEIVE INTO(TRANS-DATA-IN) 
LENGTH (TDI-LENGTH) 
END-EXEC. 
SKIP2 
SEND-DATA. 
SKIP1 
EXEC CICS 
SEND FROM(TRANS-DATA-OUT) 
LENGTH (TDO-LENGTH) 
END-EXEC. 
SKIP3 
RELEASE-PSB. 
SKIP1 
MOVE TERM TO FUNCTION. 
CALL 'CBLTDLI' USING FUNCTION. 
EJECT 
CICS-ABEND. 
SKIP1 
EXEC CICS 
DUMP 
FROM(BLL-CELLS) 
LENGTH (32) 
DUMPCODE ( 'ABLL') 
END-EXEC. 


DUMP 
FROM(DLIUIB) 
LENGTH(16) 

DUMPCODE ( 'AUIB') 
END-EXEC. 
SKIP1 
EXEC CICS 

DUMP 
FROM(PCB-PTRS) 
LENGTH (48) 
DUMPCODE ('APTR') 
END-EXEC. 
EJECT 
EXEC CICS 

DUMP 
FROM(PCB1) 
LENGTH (256) 
DUMPCODE ( 'APCB') 
END-EXEC. 
SKIP3 
PERFORM RELEASE-PSB. 
SKIP1 
EXEC CICS 

ABEND 

ABCODE (ABEND-CODE) 
END-EXEC. 
EJECT 


Figure E-4 (Part 5 of 7). CICS/VS Program Used by the Host System 
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KKEKRKEKKEKREKKREKEKRKERKEREREREERERERERERERERREERREEEREKRERERERKEREKERERER 
* 


GET INVENTORY. * 
THIS ROUTINE ATTEMPTS TO READ THE INVENTORY ITEM * 
FROM THE DL/I DATABASE BASED ON THE ITEM NUMBER * 
SENT FROM THE REQUESTING AS/400 SYSTEM. IF THE * 
ITEM IS NOT FOUND ON THE DATABASE THE ROUTINE * 


WHICH CALLS THIS ONE RETURNS AN ERROR MESSAGE T0 * 
THE AS/400 SYSTEM. OTHERWISE THE 'AMOUNTS ON HAND' = 
ARE READ FROM THE DATABASE AND RETURNED TO THE * 
AS/400 SYSTEM. * 


* 


*~ + FF FF HF F HF F HF 


FEI IG ICICI ICI III IO ICICI II ICICI ICICI RIC IR IIR AI IR A IK He 
SKIP1 
GET-INVTY. 
SKIP1 
MOVE GU TO FUNCTION. 
SKIP1 
CALL 'CBLTDLI' USING FUNCTION, PCB1, 
SEGMENT-MSININO1-IN, INVTY-SEGMENT-SSA. 
SKIP1 
IF UIBFCTR NOT = NORESP 
MOVE 'ITYU' TO ABEND-CODE 
PERFORM CICS-ABEND. 
EJECT 
FIO GIO ICI ICICI ICR ICI III ICICI I ICICI RIOR IIR AI IR A I IK AOE 
* 
GET QUANTITIES ON HAND 
THIS ROUTINE GETS THE QUANTITIES ON HAND FROM UP 
TO 4 REMOTE LOCATIONS AND RETURNS THE QUANTITIES 
TO THE REQUESTING IBM AS/400 SYSTEM. IF QUANTITIES 
ARE NOT FOUND FOR SOME LOCATIONS, ZEROS ARE * 
RETURNED IN THEIR 'ON HAND' FIELDS. * 


+ FF 


* 


+ + FF FF F HF 


KKEKRKEKKEKREKKEEKRKEKEREKER KER KER ERERERREREREREREREREREREREKREEKEKRERER 
SKIP1 
GET-QTYS-ON-HAND. 
SKIP1 
PERFORM CLEAR-QTYS. 
SKIP1 
MOVE 0 TO DLI-SWITCH. 
MOVE PCBOK TO PCB1-STATUS. 
MOVE NORESP TO UIBFCTR. 
SKIP3 
PERFORM GET-QTYS. NOTE LOCATION 1. 
IF UIBFCTR = NORESP 
F QUANTITY-SEGMENT-FOUND 
MOVE MSLCHAND TO TDO-MSLCHAND1 
MOVE MSLCLOCD TO TDO-FILL1 
ELSE 
NEXT SENTENCE 
ELSE 
MOVE 1 TO DLI-SWITCH 
GO TO GET-QTYS-EXIT. 
SKIP3 
IF NOT END-OF-CHAIN 
PERFORM GET-QTYS 


Figure E-4 (Part 6 of 7). CICS/VS Program Used by the Host System 
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IF UIBFCTR = NORESP 
IF QUANTITY-SEGMENT-FOUND 
MOVE MSLCHAND TO TDO-MSLCHAND2 
ELSE 
NEXT SENTENCE 
ELSE 
MOVE 1 TO DLI-SWITCH 
GO TO GET-QTYS-EXIT. 
EJECT 
IF NOT END-OF-CHAIN 
PERFORM GET-QTYS 
IF UIBFCTR = NORESP 
IF QUANTITY-SEGMENT-FOUND 
MOVE MSLCHAND TO TDO-MSLCHAND3 
ELSE 
NEXT SENTENCE 
ELSE 
MOVE 1 TO DLI-SWITCH 
GO TO GET-QTYS-EXIT. 
SKIP3 
IF NOT END-OF-CHAIN 
PERFORM GET-QTYS 
IF UIBFCTR = NORESP 
IF QUANTITY-SEGMENT-FOUND 
MOVE MSLCHAND TO TDO-MSLCHAND4 
ELSE 
NEXT SENTENCE 
ELSE 
MOVE 1 TO DLI-SWITCH 
GO TO GET-QTYS-EXIT. 
SKIP3 


MEMBER NE ICII 
GET-QTYS-EXIT. EXIT. 
EJECT 
CLEAR-QTYS. 
SKIP1 
MOVE ZEROS TO TDO-MSLCHAND1, 
TDO-MSLCHAND2, 
TDO-MSLCHAND3, 
TDO-MSLCHAND4. 
SKIP3 
GET-QTYS. 
SKIP1 
MOVE GNP TO FUNCTION. 
SKIP1 
CALL 'CBLTDLI' USING FUNCTION, PCB1, 
SEGMENT-MSLCINO1-IN, QTYS-SEGMENT-SSA. 
SKIP3 
MOVE-QUANTITY. 
SKIP1 
IF MSLCLOCD = '10' 
OVE MSLCHAND TO TDO-MSLCHAND1. 
SKIP1 
IF MSLCLOCD = '20' 
OVE MSLCHAND TO TDO-MSLCHAND2. 
SKIP1 
IF MSLCLOCD = '30' 
OVE MSLCHAND TO TDO-MSLCHAND3. 
SKIP1 
IF MSLCLOCD = '40' 
OVE MSLCHAND TO TDO-MSLCHAND4 
ELSE 
EXT SENTENCE. 


Figure E-4 (Part 7 of 7). CICS/VS Program Used by the Host System 
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Example 2: AS/400 System to System/370 System (IMS/VS) 


This example consists of an AS/400 ILE RPG/400 program with DDS keywords, 
talking to a System/370 COBOL IMS/VS program. 


Not all programming considerations or techniques are illustrated in this example. 
You should review the example before you begin application design and coding. 


ILE RPG/400 Program for the AS/400 System (Program A) 
The following program (PROGARPG) is used on the AS/400 system. 


When PROGARPG is called, a display is presented. This display presents a single 
inquiry line which is 23 bytes long. The operator enters the item number on the 
inquiry line, and the local database FILEA is searched. If a matching item is found, 
up to four quantities are displayed for that item. 


If the item number is not in the local database, a request is built and sent to the 
host system. Program MSCGT005 is started and searches the host database; the 
matching item number and its associated quantities are returned to PROGARPG 
and are presented on the inquiry display. 


DDS Sources: The DDS sources for FILEA, WSFILE, and RMFILE, are illustrated 
in Figure E-5, Figure E-6 on page E-18, and Figure E-7 on page E-18. 


[RR KR KK EK ERK KK EKR EKER ERE KK EKER EKER ERR ER EKER ERE RR ER ER EK ERR EKER ERE EK 


A* * 
Ax DDS SOURCE FOR THE MASTER FILE (FILEA) * 
A* * 
BR RRR KKK KEKE KKK KAKA KKK KERR KERR KKK KKK KK KEKE RRR K ERK KKK KER ER ER EREEK 
A LIFO 

A R MASTER 

A ITMNUM 23A 

A FILLER 3A 

A QTY1 6 0 

A QTY2 6 0 

A QTY3 6 0 

A QTY4 6 0 

A K ITMNUM 


Figure E-5. DDS Source for File FILEA 
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BRR KKR KK EK EKER KEKE KEKE RARER ER ER EKER KERR ER EKER EKER ER ERE KERR ER ERERERE 


A* * 

Ax DDS SOURCE FOR THE LOCAL DISPLAY FILE (WSFILE) * 

A* * 

N&R R KKK KK EKER RK KEKE KKK KERR ERE RRR KEKE KEK ERR RRR KERR KKK KEKE KERR ERE EEEK 

A* 

A CAO1 

A CA07 

A R WSFILEIN 

A ITMNUM 23 I 2 10 

A 4l 0 4 10'INVALID ITEM NUMBER ENTERED' 
A 42 O 4 10'ITEM NUMBER NOT FOUND' 

A 0 12 10'PRESS CMD KEY 7 TO TERMINATE' 
A R WSFILEOT 

A ITMNUM 23 0 2 10 

A QTY1 6 00 4 12 

A QTY2 6 00 5 12 

A QTY3 6 00 6 12 

A QTY4 6 00 7 12 

A 0 12 10'PRESS CMD KEY 7 TO TERMINATE OR' 
A 0 13 10'CMD KEY 1 FOR ANOTHER INQUIRY' 


Figure E-6. DDS Source for File WSFILE 


[RK KR KKEK KKK KK EKER EKER KKK EKER ERK EKER ERE KERR ER ER ERE RK ER ER ERERAERREE 


Ax * 
Ax DDS FOR THE ICF COMMUNICATION FILE (RMFILE) * 
Ax * 
[RRR R KKK KKK KKK KK KAKA KKK RRR EKER KKK KKK KER EKER EERE ERK K ERE REEEEEE 
A R RMDTCH 

A 51 DETACH 

A* 

A R RMEOS 

A 52 EOS 

A* 

A R RMDATA 

A ERRFLD 3A 

A FILLR1 29A 

A ITMNUM 23A 

A FILLR2 146A 

A QTY1 6 0 

A QTY2 6 0 

A QTY3 6 0 

A QTY4 6 0 

A* 

A R RMEVOK 

A SECURITY (2 &PASSWD) 

A 53 EVOKE(&PGMID &ITMNUM) 

A 53 INVITE 

A PGMID 8A P 

A PASSWD 4A P 

A ITMNUM 23A P 


Figure E-7. DDS Source for File RMFILE 


ICF File Creation and Program Device Entry Definitions: 


to create the ICF file is: 


CRTICFF 


FILE(RMFILE) 

SRCFILE (QDDSSRC) 
SRCMBR (ICFFILE1) 
ACQPGMDEV (PGMDEV) 


E-18 sSNA Upline Facility Programming V4R1 


The command needed 


The command needed to define the program device entry is: 


ADDICFDEVE FILE(RMFILE) 
PGMDEV (PGMDEV) 
RMTLOCNAME (IMSLOC) 
CMNTYPE (*SNUF) 
DEV (YDEV) 
HOST(*IMS) or (*DEVD) 


ILE RPG/400 Program: Figure E-8 shows the ILE RPG/400 Program A for the 
AS/400 system. 


FRA RK KKK KKK KKK KEK KEK KEKE KEKE KEKE KERR EKER ERK EKER ERE REE REE REE RREREREEE 


Fx * 
Fx FILE DESCRIPTION SPECIFICATIONS * 
Fx * 
FRR AKA KAKA KKK KKK KKK KKK RRR EEK K KKK KKK KEKE ERE RKEKKKEKEKKE KK EEE RERERE 
FFILEA IF E K DISK 

FWSFILE CF E WORKSTN 

FRMFILE CF E WORKSTN 

F KNUM 1 

F KID DEV 

CR KKK KAKA KKK KKK KEK KEK KKK KK KKK RRR EKER KEK KKK KEK EKER ERK ERE EKER ER 
Cx * 
C* RPG CALCULATION SPECIFICATIONS * 
Cx * 
CRRA KAKA KKK KKK KEK EK KKK KKK KK EERE RRR K KKK KEKE KER ER ERK RERERKE EEE 
Cx 

CR KKK KAKA KA KK KKK EKER KKK KKK KEKE RRR ERE KERR K KEK ERE REE ERE REE ER ERE 
Cx * 
Cx PROMPT FOR ITEM NUMBER OR DISPLAY ERROR MESSAGE * 
Cx* * 
CHAKA KARA KAKA KKK RR E KEK KKK KKK KER EKER KERR KKK KEK ERE REE REE ERERER 
C* 

C ITMINQ TAG 

C EXFMTWSFILEIN 12 

CC kG 12 GOTO EOJ 

C SETOF 4l 

C *BLANK COMP ITMNUM 4l 

C N41 *ZERO COMP ITMNUM 4l 

Cc (41 GOTO ITMINQ 

C* 

Cx SEARCH LOCAL MASTER FILE FOR ITEM 

C* 

C SETOF 134142 

C ITMNUM CHAINMASTER 1315 

Cc 15 GOTO E0OJ 

C* 

Cx DISPLAY RESULTS OF INQUIRY 

C* 

C DSPLY TAG 

C N13 EXFMTWSFILEOT 

C N13 KA GOTO ITMINQ 

C N13 kG GOTO EOJ 

C* 


Figure E-8 (Part 1 of 2). ILE RPG/400 Program A for the AS/400 System 
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Cx ITEM NOT ON LOCAL MASTER - SEND INQUIRY TO HOST 


Cx 
13 


'axx! 


42 


ONDE ED PD CINE, CGC PERLE? 


SETOF 

SETON 

MOVEL'PGMDEV' DEV 
MOVE 'MSCGTO05'PGMID 
MOVE '0023' PASSWD 
SETON 

WRITERMEVOK 

SETOF 

READ RMDATA 

COMP ERRFLD 

SETON 

WRITERMDTCH 

SETOF 

GOTO ITMINQ 

GOTO DSPLY 


Cx CMD KEY 7 PRESSED - TERMINATE SESSION 


C EOJ 


TAG 

SETON 
WRITERMEOS 
SETON 


13 
14 


53 


53 


51 


51 


52 


LR 


EVOKE 


50 
42 


DETACH 


EOS 


Figure E-8 (Part 2 of 2). ILE RPG/400 Program A for the AS/400 System 
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IMS/VS Program Used by the Host System (Program B) 


Figure E-9 is the IMS application program used by the host system to communi- 
cate with an AS/400 system. 


IDENTIFICATION DIVISION. 


SKIP3 
KKRKEKKKRKEKR EKER KERR ERR KERR EKER ERR RRR RRR ERR ERR ERR RRR RRR RRR RERRRERRERRRREREER 
* * 
*  ICII INVENTORY INQUIRY * 
* *MSCGTO05* * 
KKRKEKKKR KKK KR KERR KERR ERR KERR RRR ERR RRR ERR ERR RRR RRR ERR RRR RRR ERRERREER 

SKIP3 

PROGRAM-ID. MSCGTOO5. 

SKIP1 

SKIP3 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 

SKIP1 


* SOURCE-COMPUTER. IBM-370-168 WITH DEBUGGING MODE. 
SOURCE-COMPUTER. IBM-370-168. 
OBJECT-COMPUTER. IBM-370-168. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT PRNT-FILE ASSIGN TO UR-S-PRNTFILE. 
EJECT 
DATA DIVISION. 
FILE SECTION. 
SKIP1 
FD PRNT-FILE LABEL RECORDS OMITTED, RECORD CONTAINS 132 
CHARACTERS. 
O01 PRINTLINE. 
02 ITEM1 PIC X(80). 
02 FILLER PIC X(12). 
02 ITEM2 PIC X(40). 
SKIP3 
WORKING-STORAGE SECTION. 
SKIP1 
1h PIC 99. 
SKIP3 


KKEKRKEKKEKREKKEKEKEKEKRKER KER ERE REE ERE REEREREREEEREKREREKRREKEKRER EER REREKEREERE 


* * 
* TRANSACTION DATA RECEIVED FROM IBM AS/400 SYSTEM * 
* * 
FIG I IOI IOI II I ICICI ICI ICICI ICICI I ICI ICICI CR ICI ICR IIR RI A IIR 
SKIP1 
01 TRANS-DATA-IN. 

05 TDI-FILL1 PIC X(1). 

05 TDI-MSINITEM PIC X(23). 

SKIP3 


KKEKKKKEKKEKKEKEKEKKERKER EERE RRRE REE REERREREEKERE EKER ERE EKER KERKEEREREREREREERE 


* * 


* TRANSACTION DATA SENT BACK TO IBM AS/400 SYSTEM * 


* * 
KKEKRKKEKKKEKKEKEKKEKKER KER REE EREREREREREEKERERERERERKEREKEREREEREKREREKERERER 


SKIP1 
Figure E-9 (Part 1 of 6). IMS/VS Program Used by the Host System 
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01 TRANS-DATA-OUT. 
05 LL PIC 999 COMP-4 VALUE 260. 
05 FILLER PIC 999 COMP-4 VALUE ZERO. 
* OUTPUT DATA FOR APPLICATION RESPONSE 
05 TDO-FILL1 PIC X(32) VALUE SPACES. 
05 TDO-MSINITEM PIC X(23) 
05 FILLER PIC X(5) VALUE SPACES. 
05 TDO-DESC PIC X(10). 
05 FILLER PIC X(130) VALUE SPACES. 
05 TDO-MGLCHAND-VALUE. 
10 TDO-MSLCHAND PIC S9(6) OCCURS 4 TIMES. 
05 TDO-FILL3 PIC X(32) VALUE SPACES. 
SKIP1 
01 ERROR-MESSAGE REDEFINES TRANS-DATA-OUT. 
05 LL PIC 999 COMP-4. 
05 FILLER PIC 999 COMP-4. 
* OUTPUT DATA FOR APPLICATION RESPONSE 
05 EM-MESSAGE PIC X(51). 
05 EM-FILLER PIC X(205). 
SKIP3 
* CONVERSATIONAL INPUT/OUTPUT DATA AREA FOR I0-PCB. 
01 SPA-AREAS. 
02 LL PIC 999 COMP-4, VALUE IS 270. 
02 FILL PIC X(4). 
02 TRAN-CODE PIC X(8). 
02 WORK-AREA. 
05 WORK-1 PIC X(24). 
05 WORK-2 PIC X(232). 
66 SPA-IN RENAMES FILL THROUGH WORK-1. 


66 SPA-OUT RENAMES FILL THRU WORK-2. 


EJECT 


KKEKKEKKRKKEKKEKEK EKER KER KER ERR RERE RR ERE EERERREE ERE KEKE REREKRKERREKERREREREREERE 


* 
* 


DL/I INVENTORY DAT 


* 


* 
TABASE SEGMENT INPUT AREA 


* 
* 


KKEKKEKKEKKEKRKEKRKKRKEK EKER EER REEKR REE RE ERRE EKER ERREER EERE KER EKRKERKEKERKEEREEKEREERE 


SKIP1 

01 SEGMENT-MSININO1-IN. 
05 MSINITEM PIC X(23). 
05 MSINBCOD PIC X(2). 
05 MSINCOST PIC S$9(7) COMP-3. 
05 MSINDESC PIC X(10). 
05 FILLER PIC X(6) VALUE SPACES. 
SKIP3 

01 SEGMENT-MSLCINO1-IN. 
05 MSLCLOCD PIC 9(2). 
05 MSLCHAND PIC S$9(9) COMP-3. 
05 MSLCALOC PIC $9(9) COMP-3. 
05 MSLCCLOC PIC S$9(9) COMP-3. 
05 MSLCBORD PIC S9(9) COMP-3. 
05 MSLCWORK PIC S$9(9) COMP-3. 
05 FILLER PIC X(8) VALUE SPACES. 
SKIP3 
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KKEKRKEKKEKREKKEKEKRKEKERKEREER ERE REREREER EERE RERREREEKERKEKEREKEKREREEREKRERERERERERE 


* 


* 


* DL/I INVTY DATABASE SEGMENT SEARCH ARGUMENTS (SSA'S) * 
* * 
FEI GIO IC ICI ICG I ICICI IC ICICI ICI RICCI ICICI ICI ICR A IRR II A I IR 
SKIP1 
01 INVTY-SEGMENT-SSA. 
05 FILLER PIC X(19) VALUE 'MSININO1(MSINITEM ='. 
05 SSA-MSINITEM PIC X(23). 
05 FILLER PIC X(1) VALUE ')'. 
SKIP3 
01 QTYS-SEGMENT-SSA. 
05 FILLER PIC X(9) VALUE 'MSLCINO1'. 
SKIP3 
FIG ICI ICI IOI ICI ICICI ICI ICICI ICI ICICI I IIR ICI ICR IIR RI A IIR 
* * 
* MISCELLANEOUS WORKING-STORAGE AREAS * 
* * 


KKEKRKEKKEKEKEKKEKKEKKERKER ERE REE RERERERRERERREEKEREE EKER ERR EKEKEREREREREKERERER 


SKIP1 

01 DLI-FUNCTIONS. 
05 GU PIC X(4) VALUE 'GU '. 
05 GN PIC X(4) VALUE 'GN '. 
05 GNP PIC X(4) VALUE 'GNP '. 
05 ISRT PIC X(4) VALUE 'ISRT'. 
SKIP3 

01 MSG-NOT-FOUND. 
05 FILLER PIC X(11) VALUE '***ERROR***'. 
05 FILLER PIC X(6) VALUE ' ITEM '. 
05 MSG-MSINITEM PIC X(23). 
05 FILLER PIC X(12) VALUE ' NOT FOUND. '. 
SKIP3 
EJECT 

LINKAGE SECTION. 
SKIP1 

01 I0-PCB. 
05 TERM-NAME PIC X(8). 
05 FILLER PIC XX. 
05 I0-STATUS PIC XX. 
05 I0-PREFIX PIC X(12). 
05 FILLER PIC X(8). 

01 PCB1. 


@5 PCB1-DBD-NAME PIC X(8). 
@5 PCB1-SEG-LEVEL PIC X(2). 
05 PCB1-STATUS PIC X(2). 
88 SEGMENT-FOUND VALUE ' '. 
88 SEGMENT-END VALUE 'GE'. 
@5 PCB1-PROC-OPTN PIC X(4). 
05 PCB1-FILL1 PIC $9(5) COMP. 
@5 PCB1-SEG-NAME PIC X(8). 
@5 PCB1-LENG-KFBA PIC S9(5) COMP. 
@5 PCB1-NUMBOSSEG PIC S9(5) COMP. 
05 PCB1-KEY-FBA PIC X(256). 
EJECT 
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KKEKKEKKEKEKEKRKEKRKEKKER KER KER ERE REE RE EREEEREREEERERRE KER EKER ERE EREREEKEREERE 


* * 
* MAIN LINE ROUTINE * 
* * 


KKEKKEKKEKEKKEKEKKEKKER KER KERR ERR RRR REERREEREREREEEREREREREREREKREREREEEREERE 
SKIP1 
PROCEDURE DIVISION. 
SKIP1 
DECLARATIVES. 
DEBUG-IMS SECTION. USE FOR DEBUGGING ON ALL REFERENCES 
PCB1. 
DEBUG-IMS-RTN. 
D EXHIBIT NAMED PCB1. 
END DECLARATIVES. 
SKIP3 
BEGIN-IMS SECTION. 
BEGIN-PROCESSING. 
ENTRY 'DLITCBL' USING I0-PCB, PCB1. 
OPEN OUTPUT PRNT-FILE. 
READY TRACE. 
READ-TERMINAL. 
CALL 'CBLTDLI' USING GU, IO-PCB, SPA-IN. 
D EXHIBIT NAMED I0-PCB, SPA-IN. 
IF IO-STATUS EQUAL TO 'QC' GO TO CLOSING, 
ELSE IF IO-STATUS NOT EQUAL SPACES MOVE IO-PCB TO ITEM1, 
MOVE 'GU FOR ID-PCB' TO ITEM2, GO TO ABEND. 
* CALL 'CBLTDLI' USING GN, IO-PCB, SPA-IN. 
D EXHIBIT NAMED I0-PCB, SPA-IN. 
MOVE 'GN FOR IO-PCB, TO ITEM2. 


IF IO-STATUS EQUAL 'QD' NEXT SENTENCE, 

ELSE IF IO-STATUS NOT = SPACES MOVE IO-PCB TO ITEM1, 
GO TO ABEND. 
MOVE WORK-1 TO TRANS-DATA-IN. 


MOVE TDI-MSINITEM TO SSA-MSINITEM. 
SKIP3 
KKEKRKEKKERKEKEREKRKERKRRKEKER KER REE EERE REEREEREEREEERERRE EER ERE RERERKEREKEKREREEKEE 
* 
GET INVENTORY 
THIS ROUTINE ATTEMPTS TO READ THE INVENTORY ITEM FROM THE 
DL/I DATABASE BASED ON THE ITEM NUMBER SENT FROM THE 
REQUESTING AS/400 SYSTEM. IF THE ITEM IS NOT FOUND ON THE * 
DATABASE, THE ROUTINE WHICH CALLS THIS ONE RETURNS AN * 
ERROR MESSAGE TO AS/400 SYSTEM. OTHERWISE THE 'AMOUNTS OF «* 
HAND' ARE READ FROM THE DATABASE AND RETURNED TO * 
THE AS/400 SYSTEM. * 


* 


+ + 


a ee A eo 


FIG IOI III ICICI I ICICI ICI ICI ICICI ICI II ICICI RIOR ICI ICR AI IR A I RAE 
SKIP1 
GET-INVTY. 
CALL 'CBLTDLI' USING GU, PCB1, SEGMENT-MSININO1-IN, 
INVTY-SEGMENT-SSA. 
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D EXHIBIT NAMED SEGMENT-MSININO1-IN. 

IF SEGMENT-FOUND 
MOVE ZEROS TO TDO-MSLCHAND-VALUE, 
MOVE TDI-MSINITEM TO TDO-MSINITEM, 
MOVE MSINDESC TO TDO-DESC, 
PERFORM GET-QTYS UNTIL SEGMENT-END, 
PERFORM SEND-DATA, 

SKIP2 


KKEKRKKKEKKEKKKEKEKKERKEERKEEREKRERERREREREREERERERERERKEREKEKREREERERERERERERER 


THIS ROUTINE IS EXECUTED IF THE INQUIRY INVENTORY 
ITEM READ IS NOT FOUND IN DATABASE. A MESSAGE 

IS BUILT TO BE SENT BACK TO THE ORIGINATING LOCATION. 
MESSAGE IS: 


***ERROR*** ITEM #tttttttHX (23) d#tttt i i NOT FOUND 


+ + FF FF F 
+ + FF F F HF 


FEI GIO ICI II ICI ISIC ICI ICICI RICCI I ICICI RCI ICR ICI ICR ACR II A I IR 
ELSE IF SEGMENT-END 
MOVE TDI-MSINITEM TO MSG-MSINITEM, 
MOVE SPACES TO EM-FILLER, 
MOVE MSG-NOT-FOUND TO EM-MESSAGE, 
PERFORM SEND-DATA, 


SKIP2 
FIGS ICICI ICI III ICICI ICI ICICI ICR RICCI A ICC ICI ICR IIR RIC A I IK 
* * 
* FORCE ABEND, ERROR IN PROGRAM, AND DEBUG * 
* * 


FIG II GIO ICI ICI ICI ICG ICICI ICI ICICI RICCI I ICICI I ICC ICI RAC ICI A IR 

SKIP1 

ELSE MOVE PCB1 TO ITEM1, MOVE 'GU ON PCB1' TO ITEM2, 
GO TO ABEND. 

CLOSING. CLOSE PRNT-FILE. 
* SET TRANSACTION CODE IN SPA TO TERMINATE CONVERSATION 

MOVE SPACES TO TRAN-CODE. 

CALL 'CBLTDLI' USING ISRT, I0-PCB, SPA-AREAS. 


RESET TRACE. 
STOP RUN. 


KKEKRKEKKEKREKKEKEKRKKERKER EER REKEKERERERREEREEKEREKRER EERE KKREKEKREREERERERERERERERER 


* * 
* CLOSED SUBROUTINES * 
* * 


FAIS RIO GIORGIO IG GIGS ICICI ICI II ICR IR AI Ke 
SKIP1 
EJECT 


KKEKRKEKKEKEKKEKEKKEKKERKER REE ERE REREREREREREREKRERERERKEREKEREREREREREREREREER 


GET QUANTITIES ON HAND 
THIS ROUTINE GETS THE QUANTITIES ON HAND FROM UP TO 4 
REMOTE LOCATIONS AND RETURNS THE QUANTITIES TO THE 
REQUESTING IBM AS/400 SYSTEM. IF QUANTITIES ARE NOT 
FOUND FOR SOME LOCATIONS, ZEROS ARE RETURNED IN THEIR 
"ON HAND' FIELDS. 


+ + FF F F HF 
+ + FF F F F HF 


SKIP1 
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GET-QTYS. 
CALL 'CBLTDLI' USING GNP, PCB1, SEGMENT-MSLCIO1-IN, 
QTYS-SEGMENT-SSA. 
D EXHIBIT NAMED SEGMENT-MSLCINO1-IN. 
IF SEGMENT -FOUND PERFORM DETERMINE-LOCATION, 
MOVE MSLCHAND TO TDO-MSLCHAND (1), 
ELSE IF NOT SEGMENT-END MOVE PCB1 TO ITEM1, MOVE 
"GNP ON PCB1' TO ITEM2, GO TO ABEND. 
SKIP3 
DETERMINE-LOCATION. 
IF MSLCLOCD - 21 MOVE 1 TO I 
ELSE IF MSLCLOCD = 41 MOVE 2 TO I, 
ELSE IF MSLCLOCD = 51 MOVE 3 TO I, 
ELSE IF MSLCLOCD = 81 MOVE 4 TO I. 


SKIP3 
FEI IGRI ICI ICI ICR I ICICI ICI ICICI ICI I ICI RCI CIR ACI ICR IIR II A I IR 
* * 
* SEND IMS MESSAGE TO QUEUE FOR ROUTING TO ORIGINATING * 
* AS/400 LOCATION * 
* * 
FIO III III IC IO ICICI ICI ICICI ICI ICICI ICICI CR ACI IR ICR ICI A AIK 
SKIP1 
SEND-DATA. 


* SET TRANSACTION CODE IN SPA TO END CONVERSATION 
MOVE SPACES TO TRAN-CODE. 
CALL 'CBLTDLI' USING ISRT, I0-PCB, SPA-AREAS. 


INSERT DATA MESSAGE FOR TRANSMISSION TO REQUESTER 


a 


CALL 'CBLTDLI' USING ISRT, I0-PCB, TRANS-DATA-OUT. 
D EXHIBIT NAMED TRANS-DATA-OUT. 
IF IO-STATUS NOT EQUAL SPACES MOVE TO-PCB TO ITEM1, 
MOVE 'ISRT FOR I0-PCB' TO ITEM2, GO TO ABEND. 
SKIP3 
ABEND. 
WRITE PRINTLINE AFTER ADVANCING 2 LINES. 
MOVE SPACES TO PRINTLINE. MOVE ‘ABEND OCCURRED' TO ITEM2. 
WRITE PRINTLINE. GO TO CLOSING. 
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Example 3: AS/400 System to System/370 System (CICS/VS) 


The following example consists of an AS/400 ILE C/400 program using system- 
supplied ICF formats, communicating to a System/370 COBOL CICS/VS program. 
For the program used by the host system to communicate with the AS/400 system, 
see “CICS/VS Program Used by the Host System (Program B)” on page E-10. 


As discussed in previous examples, not all programming considerations or tech- 
niques are illustrated in this example. You should review the example before you 
begin to design and code your application. 


ILE C/400 Program for the AS/400 System (Program A) 
The following program is used on the AS/400 system. 


When the PROGAC program is called, a display is presented. This display pre- 
sents a single inquiry line which is 23 bytes long. The operator enters the item 
number on the inquiry line, and the local database file, FILEA, is searched. lf a 
matching item is found, up to four quantities are displayed for that item. 


If an item number is not in the local database, a request is built and sent to the 
host system. The ICII program is started and searches the host system database. 
The matching item number and its quantities are returned to the PROGAC program 
and are presented on the inquiry display. 


DDS Sources: The DDS sources for DISPFILE and FILEA are illustrated in 
Figure E-10 and Figure E-11 on page E-28. 


[RR KKR KK EKER KK EKR EKER ERK KK EKER ERE KERR ER EKER ERK ER EKER EKER ER ER EKER 


A* * 

Ax LOCAL DISPLAY FILE * 

A* * 
[RRA KKK KKK KKK EKER KEKE RRR ERK KEKE RE REE KEK ERE RREEE 

A* 

A CAO1 

A CAQ7 (99) 

A R WSFILEIN 

A ITMNUM 23 I 2 10 

A 01 O 4 10'INVALID ITEM NUMBER ENTERED' 
A 02 O 4 10'ITEM NUMBER NOT FOUND' 

A 0 12 10'PRESS CMD KEY 7 TO TERMINATE' 
A R WSFILEOT 

A ITMNUM 23 0 2 10 

A QTY1 6 00 4 12 

A QTY2 6 00 5 12 

A QTY3 6 00 6 12 

A QTy4 6 00 7 12 

A MSG 80 O 8 10 

A RETCOD 4 010 10 

A REASON 30 0 11 10 

A FILLER 95 0 12 10 

A 0 14 10'PRESS CMD KEY 7 TO TERMINATE OR' 
A 0 15 10'CMD KEY 1 FOR ANOTHER INQUIRY' 


Figure E-10. DDS Source for DISPFILE 
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[RR KKRKK EKER KK ER EKER ERE KK ER ER EK ERK EKER EK ERE KERR ER ERE KERR ER ERERERE 


A* * 
Ax DDS SOURCE FOR THE MASTER FILE (FILEA) * 
A* * 
Nk RRR KK KKK EKER KKK KKK KERR EERE RRR KKK KK EK ERR EKER RK KKK KKK ERE REE ERER 
A LIFO 

A R MASTER 

A ITMNUM 23A 

A FILLER 3A 

A QTY1 6 0 

A QTY2 6 0 

A QTY3 6 0 

A QTY4 6 0 

A K ITMNUM 


Figure E-11. DDS Source for File FILEA 


Program Device Entry Definition: The command needed to define the program 
device entry is: 


ADDICFDEVE FILE(*LIBL/QICDMF) 
PGMDEV (SNUFDEVICE) 
RMTLOCNAME (CICSLOC) 
CMNTYPE(*SNUF) 
DEV (XDEV) 
APPID(CICS) 
HOST(*DEVD) or (*CICS) 


ILE C/400 Program: Figure E-12 on page E-29 shows the ILE C/400 program 
PROGAC for the AS/400 system. 
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[BRK RRKA KI KIRKE AKI KEKE AKA KIK REA KAKI K ERE AKA KEK IR | 


/* PROGAC ITEM INQUIRY WRITTEN IN ILE-C */ 


[RRR RRR IKI KIRK ER KA KIRK EA KAKI KERR KAKI KERRI KEKE | 


#pragma mapinc("dspf","icflib/dispfile(*all)","both indicators","p z") 


#include "dspf" 

#pragma mapinc("fileainc", “icflib/filea(*all)", “input", "p z") 
#include "fileainc" 

#include <stdio.h> /* Standard 1/0 header */ 
#include <recio.h> /* Record I/0 header */ 
#include <stdlib.h> /* General utilities */ 
#include <stddef.h> /* Standard definitions */ 
#include <string.h> /* String handling utilities */ 
#include <xxfdbk.h> /* Feedback area structures */ 
#define ERROR 1 /* error occured */ 
#define NOERROR 0 /* no error occured */ 
#define ION '1' /* indicator set on */ 
#define IOFF 'Q' /* indicator set off */ 
#define SPACE ' ' /* spaces for memset */ 
#define BLNK23 " "/* 23 blanks */ 
#define ZERO23 "QoQ00000000000000000000" /* 23 zeros */ 
[RRR RRA KIKI KER ERK AKIRA KI KIKI KA KIRK IK KAR IK KAIRIE KEKE AKA KEKE | 
/* Global Variables */ 
[RRR KIKI K IKEA KI KIK ERIKA KIKI EK RIK IK IKEA KI KIRK IEA KIKI K IERIE AKAIKE | 
_RFILE *icfptr; /* ptr to ICF file */ 
_RFILE *dspfptr; /* ptr to display file */ 
_RFILE *fileaptr; /* ptr to fileA */ 
_RIOFB_T *rio_fbk; /* ptr to partial I/0 feedback */ 
_XXIOFB_T *comm_fdbk; /* ptr to common I/0 feedback */ 
_XXIOFB_DSP_ICF_T *icf_fdbk; /* ptr to icf feedback */ 
[RRR KAKI K IKE KAKI KIK RAK AKIRA KIKI K IKEA KI KIRK IEK KAKI K IERIE AKAIKE | 
/* Structure to be used for return code */ 
[BRR RR KIKI K KER KAKI KI KERR KI KIKI KA KIK ERIK KAR IK IKK A RIKER EAA RIKER | 
struct { 


char major??(2??); 
char minor??(2??); 
}return_code; 
FORO ESOS ISOC OSES ISOS OC OCICS COICO CIC I TTI III II TAI A A | 


/* Structure to be used in the evoke processing */ 
[RRR KIKI K IKEA KI KIK REIKI KIKI KIRK IA KAR IK ERIK KAKI K ERIE AKAIKE | 
struct { 


char proc_name??(8??); 
char password?? (8??); 
char user_id??(8??); 
char libr_name??(8??); 
char filler??(20??); 
char data_length??(4??); 
char evok_data??(23??); 
}evok_record; 

struct { 
char data??(32??); 
char number_in??(23??); 
char filler2??(145??); 
char icf_qty1??(6??); 
char icf_qty2??(6??); 
char icf_qty3??(6??); 
char icf_qty4??(6??); 
char filler3??(32??); 
}icf_record; 

[RRR KIKI KIRK AKI KIRK IK KI KIKI KI KIK IKK I KIKI KIA KAKI K IKEA AKER ER | 


/* Structure to be used in the end of transaction processing */ 
[BRK I KI KIKI RR KI KIKI KI KIKI KI KIRKE AKI KIKI IK KAKI K ERIK KAKI K ER | 
struct { 


char length??(4??); 
char data??(80??); 
}eot_rec; 

char input_buffer?? (409627?) ; 


Figure E-12 (Part 1 of 6). ILE C/400 Program for the AS/400 System 
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[BRR RR KIKI KI KIRK AKI KI KIRK KA KIKI KAKI RIK IK EAA RIK IK EAA KI KIRKE AKER | 


/* Structure to be used to write to display file */ 
[RRR KIKI KIKI REIKI KI KIKI KAKI KIK EAI KIK IK EAA KIKI KAKA KIKI KE AKA KAKI | 
ICFLIB_DISPFILE_WSFILEIN. 0 t wsfilein_o; /* display file input */ 
ICFLIB_DISPFILE_WSFILEIN i_t wsfilein_i; /* display file input */ 


ICFLIB_DISPFILE_WSFILEOT_o t wsfileot_o; /* display file output */ 
ICFLIB_DISPFILE_WSFILEOT_i_t wsfileot_i; /* display file output */ 


ICFLIB_FILEA MASTER_i_t itmfile; /* data file structure */ 
[RRR KIKI K IKE REIKI KI KKK AKI RIK IK EAI IK IKEA A KIKI K IAAI KEKE AEA KEK ER | 
/* Prototyping of routines */ 


[RRR RRA I KIKI R KAKA KIRKE AKIRA KKK AK IK EKA AK IKIK EAA KIKI K EAI ARIK | 
int open_files(void); 

int read_filea(void); 

int icf(void); 

int logon_evoke(void) ; 

void send_eos(void); 

void close _files(void); 

int check_return_code(void); 

[RRR KIKI KI KIRK AKA KIKI KER A KIKI KAKI KIK IK EAA RIK IK EAA KIKI K EAA KEKE | 


/* main procedure begin */ 
[BIRR KIKI K AKIRA KIKI KIKI KI KIKIK AKI KIKI KAKI KIK IK IAA KIKI KEKE AKI KER | 
main() 
{ 
if (open_files() == ERROR) 
exit (ERROR) ; 
[BIKA RRR KAKI KI KIRK AKI KI KIKI KAKI KIKI KA KAR IK EAA KIKI K IAAI KERR | 
/* Display the screen that will request the number. */ 
/* If CMD7(99) then close the files and end. */ 
/* Set up indicators to display errors if item number */ 
/* iS zero or spaces. */ 


[BRR I RRR ER KIKI K IR KIKI KI KIKI I KIKI KAIRIE KIKI AKA KI KIKI AKAIKE RIE | 
wsfilein_i.IN99flO“ = IOFF; 
wsfileot_i.IN99fl0“ = IOFF; 
while ((wsfilein_i.IN99fl0% == IOFF) & (wsfileot_i.IN99fi0“ == IOFF)) 
{ 
_Rformat(dspfptr, "WSFILEIN"); 
_Rwrite(dspfptr, &wsfilein_o, sizeof(wsfilein_o)); 
_Rreadn(dspfptr, &wsfilein_i, sizeof(wsfilein_i), _ DFT); 
if (wsfilein_i.IN99fl0% == IOFF) 
{ 
wsfilein_o. INO1fl0“ = IOFF; 
wsfilein_o. INO2flO = IOFF; 
memset (wsfileot_o.RETCOD, SPACE , 4); 
memset (wsfileot_o.REASON, SPACE , 30); 
if ((strcmp(wsfilein_i.ITMNUM, BLNK23) == 0) || 
(strcmp(wsfilein_i.ITMNUM, ZERO23) == 0)) 
wsfilein_o.INO1A0 = ION; 
else 
{ 
if (read_filea() == ERROR) 
if (icf() == ERROR) 
wsfilein_o. INO2fl0“ = ION; 
} /* if not 0 or " " */ 
if (wsfilein_o. INO2fl0“ == IOFF & wsfilein_o.INO1fi0~ == IOFF) 
{ 
_Rformat(dspfptr, "WSFILEOT"); 
_Rwrite(dspfptr, &wsfileot_o, sizeof (wsfileot_o)); 
_Rreadn(dspfptr, &wsfileot_i, sizeof(wsfileot_i), _ DFT); 


} /* end send data out to display */ 

} /* end if CMD7 was issued in Display filex/ 

} /* end while CMD7 not issued */ 
close_files(); 

} /* end main procedure */ 


Figure E-12 (Part 2 of 6). ILE C/400 Program for the AS/400 System 
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[BRK R RRA KI KIRKE AKA KIK REA KI KIKI KA KIKI RIKKI RIKKI KAKI K ERIK KAKI K ER | 
/* open files procedure */ 
[RRR REIKI KIRKE AKI KIK REIKI KIKI KI KIRK IEK KAR IK ERIKA KAKA KAKA K ER | 
int 
open_files(void) 
[RRR RR KAKI KIRKE AKI KIKI EK KA KIRKE KA KIKI KA KIKI KIARA KARE RK | 
/* open ICF file */ 
[RRR RR KAKI KIKI KI KIKI EK KI KIKI AKA RIKKI A KIKI KIRA A RIKER ERK | 
if ((icfptr = Ropen("QICDMF", "ar+ indicators=y riofb=y")) == NULL) 
return(ERROR) ; 
[BIKAR RR KAKI K EKER KIKI RIKER ER KA KIKI EA KA KIRKE AKAIKE AKA KEKE ERK | 
/* open file A x/ 
[BIRR RR KAKI K EKER KIKI KIKI KI KIKI EK KA KIRK IEK KA KIKI REAR A KEKE RK | 
if ((fileaptr = Ropen("FILEA", "rr+ riofb=y")) == NULL) 
_Rclose(icfptr); 
return(ERROR) ; 


[BIKAR RR KIKI K AKER KAKI KIKI KI KIRKE RIK IK KIA KAR IK IKEA KAKI K IKEA | 
/* open display file */ 
[IKK RR KAKI RIKER KAKI KIRK EA KI KIRKE AKA KIKI IEK KAKI K IKEA KARIERRE RK | 


if ((dspfptr = Ropen("dispfile", "“ar+ riofb=y")) 


== NULL) 
{ 
_Rclose(icfptr) ; 
_Rclose(fileaptr) ; 
return(ERROR) ; 
} 
return(NOERROR) 
} /* end open files procedure */ 
[RRR KIKI K KER KA KIKI KERR KI KIRKE KA KIKI A KIKI K IAAI KIRA A KEKE | 
/* read filea procedure */ 


[RRR KIKI KIK REIKI KIKI EK KI KIKI AKA KEK K IAI KIK KIKI KIKI K IKI KI KER | 
int 
read_filea(void) 
{ 
_Rformat(fileaptr, "ITEM"); 
rio_fbk = Rreadk(fileaptr, &itmfile, sizeof(itmfile), __KEY_EQ, 
wsfilein_i.ITMNUM, sizeof (itmfile.ITMNUM)); 
if (rio_fbk->num_bytes == 0) 
return(ERROR) ; 
strncpy(wsfileot_o.ITMNUM, itmfile.ITMNUM, 23); 
strncpy(wsfileot_o.QTY1, itmfile.QTY1, 6); 
strncpy(wsfileot_o.QTY2, itmfile.QTY2, 6); 
strncpy(wsfileot_o.QTY3, itmfile.QTY3, 6); 
strncpy(wsfileot_o.QTY4, itmfile.QTY4, 6); 
return (NOERROR) ; 
} /* end of read filea procedure */ 
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[BRR RR KAKI KI KER KAKA KI KKK KI KIRKE AKA KIK IK EAI KIKI KEK A KIKI K EAA KIKI | 


/* ICF file procedure */ 
[RRR RRA KIKI KERRI KI KERRI KI KIRK EAA KIK IKEA I RIK IK EAA RIKER AIA RIKER | 
int 

icf (void) 


[BRK A RRR KAKI KIKI KER KIKI KIK KAKI KIKI KE AKA KAR IK EAA KI KIKI AKAIKE REA | 
/* acquire SNUF session */ 
[BRR IRR KAKI K IKKE AKA KIKI KER I KIKI REIKI KIKI KAIRIE KIRKE IKARIA | 
Racquire(icfptr, "SNUFDEVICE"); 

if (check_return_code() == NOERROR) 


[BRR IRR KAKI KI KIRR RIKI KI KIK ERIK IK IKEA KI KIKI KAKA K IKKE AEA I KEKE RK | 
/* evoke processing evoke ICII at host */ 


[BIKAR RR KAKI KIRK KAKA RIKKI KI KAR IK ERIKA KEKE AKIRA KEKE AEA RIKER RK | 


if (logon_evoke() == NOERROR) 


[BIKAR IR KAKI KI KIRK AKI KI KIKI KAKI KIKI KAKI KIKI KAKI K IK EAA KIKI | 
/* read host data and end transaction */ 


[BIKA RRR KAKI KI KIRA KIKI KIKI A KIKI KER A KI KIKI KAKI K IK EAA RIKER ERK | 
_Rreadindv(icfptr, &icf_record, sizeof(icf_record), _ DFT); 
if (check_return_code() == NOERROR) 
{ 

_Rformat(icfptr, "$$SENDET") ; 

strncpy(eot_rec.length, "0080", 4); 

_Rwrite(icfptr, &eot_rec, sizeof(eot_rec)); 

if (check_return_code() == NOERROR) 

{ 


[BRR I RRR KAKI KI KIRK AKI KIKI KAKA KIKI KEK KAKI KIK EAA KI KIKI AEA KIKI | 
/* check if host data is valid */ 
[BIKAR RR KAKA KIRKE AKA KI KEK EAA K IKK EAA KIRK EAA KIKI K EAE AKIRA | 
if (strncmp(icf_record.data, "***", 3) == 0) 
return(ERROR) ; 


else 
{ 
strncpy(wsfileot_o.ITMNUM, icf_record.number_in, 23); 
strncpy(wsfileot_o.QTY1, icf_record.icf_qtyl, 6); 
strncpy(wsfileot_o.QTY2, icf_record.icf_qty2, 6); 
strncpy(wsfileot_o.QTY3, icf_record.icf_qty3, 6); 
strncpy(wsfileot_o.QTY4, icf_record.icf_qty4, 6); 
return (NOERROR) ; 
} /* if data = *** */ 
} /* end if end transaction was ok */ 
} /* read from ICF was good x/ 
} /* end logon and evoke ICII */ 
[BIKA KIRK KAKA KI KIRK AKI KIKI K AKI KI KIKI A KIKI KAA KI KIRKE A RAKE RIK  | 
/* if there was an error in the evoke processing, ICF read */ 
/* processing or the end of transaction processing then the */ 
/* session should be taken down. */ 


[BRK RRR KI KI KIRK KAKA KI KIKI KA KIKI KAKA KIKI KAKA KI KIRA IKARIA | 
send_eos(); 
} /* end if acquire was good */ 
return (NOERROR) ; 
} /* end of process ICF */ 
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[RRR RRA KIKI K REIKI KIK REIKI KIKI AKA KIRK IA KIKI K KAIRIE K IERIE AKA KEK ERE | 


/* Logon to CICS procedure */ 


[BRR RR KIKI KIK REA KA KIKI EA KI KIKI KI KIRKE K KIKI K EKA KAKI K IERIE AKAIKE | 
int logon_evoke(void) 


[RIKKI KI KIKI KI KIKI ER KA KIRK IA KIKI K IKEA KAR IK IRIE K KAKA KIER | 
/* set up evoke structure to logon to CICS using CSSN x/ 


[RRR ER KAKI K IKE REIKI KIKI KA KIKI RIKKI RIKER EA KAKI K IERIE KEI KER ERE | 
memset (evok_record.evok_data, SPACE, 24); 


strncpy(evok_record.proc_name, "CSSN My (8) 
strncpy (evok_record.password, "USER 5: 8)5 
strncpy(evok_record.user_id, "USID "5. 8) 


strncpy(evok_record.data_length, "0024", 4); 
strncpy(evok_record.evok_data, "NAME=USER PS=USID ", 24); 
_Rformat(icfptr, "$$EVOK"); 

_Rwrite(icfptr, &evok_record, sizeof (evok_record)); 

if (check_return_code() == NOERROR) 


[RRR KIKI KIRKE AKI KIKI KI KIK REAR I RIKER K RIK IK EK IEA KAKI K ERIK | 
/* read logon response from host */ 


[RRR RRA KA KIK ERIKA KIRK EK KI KIKI EK KA KIRKE A KIRK IEK KAKI K ERE | 
_Rreadindv(icfptr, &input_buffer, sizeof(input_buffer), _ DFT); 
if (check_return_code() == NOERROR) 


[BRK A KIKI KI KIKI KI KIKI KA KIKI KERRI KIKI IEA KAKI K IERIE REAR | 
/* read detach response from host */ 


[BRK I RIKKI K AKIRA KI KIKI KI KIKI IEK RIK IK IKEA KAR IK IKEA RAKE | 
_Rformat(icfptr, "DFTRCD"); 

_Rreadn(icfptr, &input_buffer, sizeof(input_buffer), _ DFT); 

if (check_return_code() == NOERROR) 


[IKK RR KIKI K EKER EI KI KIRKE AKI KI KIK AKA KAR IEK IKK A KIKI REA A KEKE | 
/* set up evoke structure to start up ICII program */ 


[RIKI A KI KIKI EA KI KIRK EK RAK IK KAKI KIKI KIKI K IERIE AKIRA K ERE | 
memset (evok_record.evok_data, SPACE, 24); 


strncpy(evok_record.proc_name, "ICII ", 8); 
strncpy(evok_record.data_length, "0023", 4); 
strncpy(evok_record.user_id, "USER ", 8); 
strncpy(evok_record.password, "USID ",5:8)3 


strncpy(evok_record.evok_data, wsfilein_i.ITMNUM, 23); 
_Rformat(icfptr, "$$EVOK"); 

_Rwrite(icfptr, &evok_record, sizeof (evok_record)); 

if (check_return_code() == NOERROR) 


{ 
return(NOERROR) ; 
} /* end if data evoke is good */ 
} /* end if read detach indication */ 
} /* end read LOGON response */ 
} /* end write LOGON to CICS evoke */ 
return(ERROR) ; 
} /* end of send end of session */ 
[RRR I KIKI KER AKI KIKI KI KIKI KAR IK ERIK KI KIKI KAKI K IER ER KAKI K ERE | 
/* send end of session procedure */ 


[RRR RRA KI KIK ERE AKI KEKE KI KIKI KIKI EK RAK IK IKEA KA KIKI AKAIKE | 
void send_eos(void) 
{ 
Rformat(icfptr, "$$E0S"); 
“Rwrite(icfptr, &icf_record, sizeof(icf_record)); 


} /* end of send end of session */ 
[RRR KI KI KIRKE AKA KIRKE KI KI KIRA RAK IKIK IK KAR IK ERIKA KIRKE AKAIKE | 
/* close files procedure x/ 


[BRR RRA KI KIRK ER KIKI KERR KI KIRK KI RIK IK AKA KIKI K AKIRA KEKE AKA KARE | 
void close _files(void) 


{ 
_Rclose(icfptr) ; 
_Rclose(dspfptr) ; 
_Rclose(fileaptr) ; 
} /* end of close files */ 
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[BIKER KIKI RIK ER KIKI KI KIRA KIKI KIK AKAIKE KAKA KIK KEK IA KIKI KERIKERI | 


/* Check return code procedure */ 
[RRR RRA K IKI KIRKE AKI KI KIRKE I RIK IR AKI RIKKI AKIRA KKK IA KIRKE RIA KEKE | 
int 


check_return_code(void) 
{ 
comm_fdbk = _Riofbk(icfptr); 
icf_fdbk = (_XXIOFB_DSP_ICF_T *)((char *)comm_fdbk + 
comm_fdbk->file_dep_fb_offset) ; 
(strncmp(icf_fdbk->major_ret_code, "00", 2) == 0) || 
(strncmp(icf_fdbk->major_ret_code, "02", 2) == 0) || 
(strncmp(icf_fdbk->major_ret_code, "03", 2) == @)) 
return(NOERROR) ; 
else /* error case */ 
{ 
strncpy(return_code.major, icf_fdbk->major_ret_code, 2); 
strncpy(return_code.minor, icf_fdbk->minor_ret_code, 2); 
memcpy (wsfileot_o.RETCOD, &return_code, 4); 
if (strncmp(icf_fdbk->major_ret_code, "04", 2) == 0) 


if ( 


(strncpy(wsfileot_o.REASON, "Output Exception ", 30)); 

else 

if (strncmp(icf_fdbk->major_ret_code, "82", 2) == 0) 

(strncpy(wsfileot_o.REASON, "Unable to Acquire ", 30)); 

return(ERROR) ; 

} /* end if return is not good */ 
} /* end of return code check */ 
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SNUF network example 1-2 
communications session 
ending 4-12 
starting 4-6 
communications transaction 
ending 4-12 
starting 4-7 
communications type (CMNTYPE) parameter 4-3 
completing 
input operation 5-11 
configuration 
CICS/VS C-5 
command parameter 4-5 
compared to command parameters 4-5 
creating a line description 2-1 
creating descriptions 2-1 
IMS/VS_ C-8 
configuring 
SNUF 2-1 
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considerations 
batch session 5-2 
timer function 5-2 
contention mode 
See half-duplex communications 
control block program C-10 
controller description 
creating 2-1 
Create Controller Description (SNA Host) 
(CRTCTLHOST) command 2-1 
Create Device Description (SNUF) (CRTDEVSNUF) 
command 2-1 
Create Intersystem Communications Function File 
(CRTICFF) command 4-1 
Create Line Description (Ethernet) (CRTLINETH) 
command 2-1 
Create Line Description (IDLC) (CRTLINIDLC) 
command 2-1 
Create Line Description (SDLC) (CRTLINSDLC) 
command 2-1 
Create Line Description (Token-Ring) (CRTLINTRN) 
command 2-1 
Create Line Description (X.25) (CRTLINX25) 
command 2-1 
creating 
controller description 2-1 
device description 2-1 
ICF file 4-1 
line description 2-1 
CRTCTLHOST (Create Controller Description (SNA 
Host)) command 2-1 
CRTDEVSNUF (Create Device Description (SNUF)) 
command 2-1 
CRTICFF (Create Intersystem Communications 
Function File) command 4-1 
CRTLINETH (Create Line Description (Ethernet)) 
command 2-1 
CRTLINIDLC (Create Line Description (IDLC)) 
command 2-1 
CRTLINSDLC (Create Line Description (SDLC)) 
command 2-1 
CRTLINTRN (Create Line Description (Token-Ring)) 
command 2-1 
CRTLINX25 (Create Line Description (X.25)) 
command 2-1 
CSSF (CICS/VS sign-off) transaction 
evoking on a host system 5-9 
security 5-8 
CSSN (CICS/VS sign-on) transaction 
evoke function 5-8 
evoking on a host system 5-9 
security 
considerations (CICS/VS) 5-8 
parameters 5-9 
Customer Information Control System for Virtual 
Storage (CICS/VS) system 


Customer Information Control System for Virtual 


Storage (CICS/VS) system (continued) 
COBOL application E-2 
configuration example C-5 
definition 1-1 
host systems used with 1-1 
message arrangement 5-3 
program start request 
considerations C-7 
description 5-5 
example C-7 

programming considerations 
batch sessions 5-2 
chains 5-2 
configuration example C-5 
evoke function parameters 5-8 
half-duplex communications 5-1 
improving performance 5-4 
interactive sessions 5-2 


sending a function management header 4-8 


sending messages to SNUF_ 5-3 
sending transaction codes 5-8 
starting sessions again 5-4 
VTAM/NCP generation C-1 


remote program start request example C-7 


security 
CSSF transaction code 5-8 
CSSN transaction code 5-8 
sign-off 5-9 
sign-on 5-9 
system tasks 1-1 
using the evoke function 4-7 


D 


data 

length 1-1 

receiving 4-9 

sending 4-8 

starting atransaction 4-7 

data description specifications (DDS) 

example application program E-17 

keyword 
all-write (ALWWRT) A-2 
ALWWRT (allow-write) A-2 
CANCEL (cancel) 4-10, A-2 
cancel-invite (CNLINVITE) A-2 
CNLINVITE (cancel-invite) A-2 
DETACH (detach) A-2 
end-of-group (ENDGRP) A-2 
end-of-session (EOS) 4-13, A-2 
ENDGRP (end-of-group) A-2 
EOS (end-of-session) 4-13, A-2 
EVOKE (evoke) 4-7, A-2 
FAIL (fail) A-2 
FMH (function management header) 
function management header (FMH) 


A-2 
A-2 


data description specifications (DDS) (continued) 


keyword (continued) 
INVITE (invite) 4-9, A-2 
negative-response (NEGRSP) 4-11, A-2 
NEGRSP (negative-response) 4-11, A-2 
RCVCANCEL (receive-cancel) 4-11, A-2 
RCVCONFIRM (receive-confirm) A-2 
RCVDETACH (receive-detach) A-2 
RCVENDGRP (receive-end-of-group) A-2 
RCVFMH (receive-function management 
header) A-2 
RCVNEGRSP (receive-negative-response) 
RCVTRNRND (receive-turnaround) A-2 
receive-cancel (RCVCANCEL) 4-11, A-2 
receive-confirm (RCVCONFIRM) A-2 
receive-detach (RCVDETACH) A-2 
receive-end-of-group (RCVENDGRP) A-2 
receive-function management header 
(RCVFMH) A-2 
receive-negative-response (RCVNEGRSP) 
receive-turnaround (RCVTRNRND) A-2 
RECID (record-identification) A-2 
record-identification (RECID) A-2 
request-to-write (RQSWRT) 4-11, A-2 


A-2 


A-2 


respond-to-confirm (RSPCONFIRM) 4-11, A-2 


RQSWRT (request-to-write) 4-11, A-2 


RSPCONFIRM (respond-to-confirm) 4-11, A-2 


SECURITY (security) A-2 
summary table A-2 

TIMER (timer) 4-12, A-2 
variable-length data (VARLEN) A-2 
VARLEN (variable-length data) A-2 


DDS (data description specifications) 


example application program E-17 

keyword 
all-write (ALWWRT) A-2 
ALWWRT (allow-write) A-2 
CANCEL (cancel) 4-10, A-2 
cancel-invite (CNLINVITE) A-2 
CNLINVITE (cancel-invite) A-2 
DETACH (detach) A-2 
end-of-group (ENDGRP) A-2 
end-of-session (EOS) 4-13, A-2 
ENDGRP (end-of-group) A-2 
EOS (end-of-session) 4-13, A-2 
EVOKE (evoke) 4-7, A-2 
FAIL (fail) A-2 
FMH (function management header) A-2 
function management header (FMH) A-2 
INVITE (invite) 4-9, A-2 
negative-response (NEGRSP) 4-11, A-2 
NEGRSP (negative-response) 4-11, A-2 
RCVCANCEL (receive-cancel) 4-11, A-2 
RCVCONFIRM (receive-confirm) A-2 
RCVDETACH (receive-detach) A-2 
RCVENDGRP (receive-end-of-group) A-2 
RCVFMH (receive-function management 

header) A-2 


Index 


DDS (data description specifications) (continued) 
keyword (continued) 
RCVNEGRSP (receive-negative-response) A-2 
RCVTRNRND (receive-turnaround) A-2 
receive-cancel (RCVCANCEL) 4-11, A-2 
receive-confirm (RCVCONFIRM) A-2 
receive-detach (RCVDETACH) A-2 
receive-end-of-group (RCVENDGRP) A-2 
receive-function management header 
(RCVFMH) A-2 
receive-negative-response (RCVNEGRSP) A-2 
receive-turnaround (RCVTRNRND) A-2 
RECID (record-identification) A-2 
record-identification (RECID) A-2 
request-to-write (RQSWRT) 4-11, A-2 
respond-to-confirm (RSPCONFIRM) 4-11, A-2 
RQSWRT (request-to-write) 4-11, A-2 
RSPCOMFIRM (respond-to-confirm) 4-11, A-2 
SECURITY (security) A-2 
summary table A-2 
TIMER (timer) 4-12, A-2 
variable-length data (VARLEN) A-2 
VARLEN (variable-length data) A-2 
defining 
protected session 5-4 
Delete Controller Description (DLTCTLD) 
command 2-2 
Delete Device Description (DLTDEVD) 
command 2-2 
Delete File (DLTF) command 4-1 
Delete Line Description (DLTLIND) command 2-2 
deleting 
controller description 2-2 
device description 2-2 
file 4-1 
line description 2-2 
detach function 4-7, 4-12 
DEV (device) parameter 4-3 
device (DEV) parameter 4-3 
device description 
creating 2-1 
deleting 2-2 
Display Controller Description (DSPCTLD) 
command 2-2 
Display Device Description (DSPDEVD) 
command 2-2 
Display File Description (DSPFD) command 4-1 
Display File Field Description (DSPFFD) 
command 4-1 


Display Line Description (DSPLIND) command 2-2 


displaying 
controller description 2-2 
device description 2-2 
field description 4-1 
file description 4-1 
line description 2-2 
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DLTCTLD (Delete Controller Description) 
command 2-2 

DLTDEVD (Delete Device Description) 
command 2-2 

DLTF (Delete File) command 4-1 


DLTLIND (Delete Line Description) command 2-2 


DSPCTLD (Display Controller Description) 
command 2-2 

DSPDEVD (Display Device Description) 
command 2-2 


DSPFD (Display File Description) command 4-1 


DSPFFD (Display File Field Description) 
command 4-1 


DSPLIND (Display Line Description) command 2-2 


E 


EMLDEV (emulation device) parameter 4-5 
emulation device (EMLDEV) parameter 4-5 
end bracket indicator 5-6 
end session with host (ENDSSNHOST) 
parameter 4-4 
end-of-group function 
definition 4-8 
end-of-session (EOS) function 4-13 
ending 
asession 4-12 
atransaction 4-12 
ENDSSNHOST (end session with host) 
parameter 4-4 
entry 
adding ICF device 4-1 
EOS (end-of-session) keyword 4-13 
$$EOS system-supplied format A-2 
error handling (IMS/VS) 5-10 
Ethernet communications line 
available for SNUF_ 1-2 
line description 2-1 
$$EVOK system-supplied format A-2 
evoke (EVOKE) keyword 4-7 
evoke function 
considerations 
CICS/VS_ 5-8 
IMS/VS_ 5-9 
CSSF transaction 5-9 
CSSN transaction 5-8 
definition 4-7 
parameter list 4-7 
parameters ignored 5-8, 5-9 
programming considerations 
CICS and IMS_ C-6 
IMS/VS_ 5-10 
security parameters 4-7 
evoke-with-detach function 4-12 
$$EVOKET system-supplied format A-2 


$$EVOKNI system-supplied format A-2 
example 
application program E-1 
AS/400 system 
COBOL application (system-supplied format) E-2 
ILE RPG/400 application (DDS format) E-17 
CICS/VS 
COBOL application E-2 
remote program start request C-7 
half-duplex communications 5-1 
IMS/VS 
COBOL application E-17 
remote program start request C-10 
record format for program start request 5-8 
sending transactions to IMS/VS_ 5-10 
SNUF communications network 1-2 
VTAM generation C-3 


F 


fail function 4-10 
$$FAIL system-supplied format A-2 
field description 
displaying 4-1 
program start request 5-6 
file 
deleting 4-1 
ICF (intersystem communications function) 
command parameters 4-2 
commands 4-1 
creation 4-1 
definition 4-1 
file (FILE) parameter 4-2 
first-of-chain indicator 5-6 
flip-flop mode 
See also half-duplex communications 
contention mode considerations 5-4 
description 5-1 
SNUF capabilities 1-1 
FMTSLT (format select) parameter 4-3 
forced terminal response mode _ 5-12 
format 
$$CANL A-2 
$$CANLINV A-2 
$$CANLNI A-2 
$$EOS A-2 
$$EVOK A-2 
$$EVOKET A-2 
$$EVOKNI A-2 
$$FAIL A-2 
$$NRSP_ A-2 
$$NRSPNI A-2 
$$POSRSP_ A-2 
$$RCD A-2 
$$SEND A-2 
$$SENDE A-2 


format (continued) 

$$SENDET A-2 

$$SENDFM A-2 

$$SENDNF A-2 

$$SENDNI A-2 

$$TIMER A-2 

of the program start request 5-5 
format identifier 5-5 
format select (FMTSLT) parameter 4-3 
formatted program interface D-6 
function 

cancel 4-10 

cancel-invite 4-11 

detach 4-7 

end-of-group 4-8 

end-of-session 4-13 

evoke 4-7 

evoke-with-detach 4-12, 5-10 

fail 4-10 

function management header 4-8 

invite 4-9 

negative-response 4-11 

release 4-13 

request-to-write 4-11 

respond-to-confirm keyword 4-11 

timer 4-12 

write-with-detach C-6 
function-management-header function 

definition 4-8 

receiving 4-8 

sending 4-8 


G 


get-attributes operation 4-12 


H 


half-duplex communications 
See also contention mode 
See also flip-flop mode 
contention mode considerations 5-4 
description 5-1 
handling 
errors (IMS/VS) 5-10 
HDRPROC (header processing) parameter 4-4 
header 
function management 4-8 
message 5-9 
processing 5-13 
header processing (HDRPROC) parameter 4-4 
high-level language (HLL) 1-1, 4-1 
HLL (high-level language) 4-1 
HOST (host type) parameter 4-4 
host message arrangement 5-3 


Index 
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host system 
CICS/VS programming considerations 
batch sessions 5-2 
chains 5-2 
configuration example C-5 
interactive sessions 5-2 
program start request example C-7 
receiving messages 5-3 
sending messages to SNUF_ 5-3 
sending transaction codes 5-8 
VTAM/NCP generation C-1 
determining maximum request/response unit 
size 5-2 
generation for VTAM/NCP_ C-1 
IMS/VS programming considerations 
batch sessions 5-2 
chains 5-2 
improving performance 5-13 
interactive sessions 5-2 
message format services 5-13 
program start requests C-10 
receiving messages 5-3 
sending messages to SNUF_ 5-3 
sending records in chains 5-2 
VTAM/NCP generation C-1 
messages 
receiving 5-3 
programming considerations 
logical unit parameters C-2 
physical unit parameters C-1 
sending function management headers C-5 
start-with-detach function C-6 
starting the logical units C-10 
using remote program start request 5-5 
VTAM BIND command C-2 
VTAM/NCP generation C-1 
write-with-detach function C-6 
security 
considerations (CICS/VS) 5-8 
parameters 5-8 
sending messages to SNUF_ 5-3 
sign-on 4-7 
used with CICS/VS_ 1-1 
used with IMS/VS_ 1-1 
valid types with SNUF_ 1-1 
host type (HOST) parameter 4-4 


l 

I/O feedback area 4-14 

ICF (intersystem communications function) 
DDS source E-17 
file considerations D-1 
file creation D-16, E-3 

ID, user 4-7 
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IDLC (integrated services digital network data link 
control) line 
available for SNUF 1-2 
line description 2-1 
ILE C/400 programming language _ 1-1 
ILE COBOL/400 programming language 
example E-1 
SNUF application 1-1 
ILE FORTRAN/400 programming language _ 1-1 
ILE RPG/400 programming language 
description 1-1 
example E-17 
improving 
performance 5-4 
IMS/SET command 4-8 
IMS/VS (Information Management System for Virtual 
Storage) system 
COBOL application example E-17 
commands 5-9 
configuration considerations C-8 
definition 1-1 
error handling 5-10 
evoke function parameters 5-9 
evoke-with-detach function 5-10 
format services 5-13 
function-management-header function 5-13 
half-duplex communications 5-1 
handling errors 5-10 
host systems used with 1-1 
improving performance 5-4 
message arrangement 5-3 
output messages 5-13 
passing message headers 5-9 
program start request example C-10 
programming considerations 
batch sessions 5-2 
improving performance 5-13 
interactive sessions 5-2 
message format services 5-13 
program start requests C-10 
sending messages to SNUF_ 5-3 
sending records in chains 5-2 
using message format services 5-13 
VTAM/NCP generation C-1 
Ready-to-Receive (RTR) command 5-11 
remote program start request example C-10 
requesting messages 5-11 
security considerations 5-10 
sending 
commands 5-9 
function management header 4-8 
transactions to IMS/VS__ 5-10 
sending commands _ 5-9 
sense data 5-10 
starting sessions again 5-4 
system tasks 1-1 


IMS/VS (Information Management System for Virtual 
Storage) system (continued) 
terminal response mode_ 5-11 
using the evoke function 4-7 
indicator 
begin-bracket 5-6 
end-bracket 5-6, C-6 
end-of-chain 5-6 
first-of-chain 5-6 
receive-cancel response 4-13 
receive-confirm response 4-13 
receive-detach response 4-13 
receive-end-of-group response 4-14 
receive-function-management header 
response 4-14 
receive-negative-response 4-14 
receive-turnaround response 4-14 
Information Management System for Virtual Storage 
(IMS/VS) system 
COBOL application example E-17 
commands 5-9 
configuration considerations C-8 
definition 1-1 
error handling 5-10 
evoke function parameters 5-9 
evoke-with-detach function 5-10 
format services 5-13 
function-management-header function 5-13 
half-duplex communications 5-1 
handling errors 5-10 
host systems used with 1-1 
improving performance 5-4 
message arrangement 5-3 
output messages 5-13 
passing message headers 5-9 
program start request example C-10 
programming considerations 
batch sessions 5-2 
improving performance 5-13 
interactive sessions 5-2 
message format services 5-13 
program start requests C-10 
sending messages to SNUF_ 5-3 
sending records in chains 5-2 
using message format services 5-13 
VTAM/NCP generation C-1 
Ready-to-Receive (RTR) command 5-11 
remote program start request example C-10 
requesting messages 5-11 
security considerations 5-10 
sending 
commands 5-9 
function management header 4-8 
transactions to IMS/VS__ 5-10 
sending commands _ 5-9 
sense data 5-10 


Information Management System for Virtual Storage 
(IMS/VS) system (continued) 
starting sessions again 5-4 
system tasks 1-1 
terminal response mode_ 5-11 
using the evoke function 4-7 
INIT-SELF D-15 
initialize self-selection (INZSELF) parameter 4-4 
input operation 5-11 
Insert Call (ISRT) operation C-10 
integrated services digital network (ISDN) 
communications line support 1-2 
interactive mode 
cancel function 4-10 
invalid communications operations 5-2 
not valid communications functions 5-2 
sending a logical record 4-8 
sending chains 5-2 
starting with write operation 4-8 
interactive session 
chains 4-10, 5-2 
interface, program 
formatted D-6 
unformatted D-4 
intersystem communications function (ICF) 
DDS source E-17 
file considerations D-1 
file creation D-16, E-3 
invalid operations during interactive sessions 5-2 
invite function 4-9 
INVITE keyword 4-9 
INZSELF (initialize self-selection) parameter 4-4 
ISDN (integrated services digital network) 
communications line support 1-2 
ISRT (Insert Call) operation C-10 


J 


job-level changes 4-5 


K 


keyword, DDS 
all-write (ALWWRT) A-2 
ALWWRT (allow-write) A-2 
CANCEL (cancel) 4-10, A-2 
cancel-invite (CNLINVITE) A-2 
CNLINVITE (cancel-invite) A-2 
DETACH (detach) A-2 
end-of-group (ENDGRP) A-2 
end-of-session (EOS) 4-13, A-2 
ENDGRP (end-of-group) A-2 
EOS (end-of-session) 4-13, A-2 
EVOKE (evoke) 4-7, A-2 
FAIL (fail) A-2 
FMH (function management header) A-2 
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keyword, DDS (continued) 


function management header (FMH) A-2 
INVITE (invite) 4-9, A-2 
negative-response (NEGRSP) 4-11, A-2 
NEGRSP (negative-response) 4-11, A-2 
RCVCANCEL (receive-cancel) 4-11, A-2 
RCVCONFIRM (receive-confirm) A-2 
RCVDETACH (receive-detach) A-2 
RCVENDGRP (receive-end-of-group) A-2 
RCVFMH (receive-function management 
header) A-2 
RCVNEGRSP (receive-negative-response) A-2 
RCVTRNRND (receive-turnaround) A-2 
receive-cancel (RCVCANCEL) 4-11, A-2 
receive-confirm (RCVCONFIRM) A-2 
receive-detach (RCVDETACH) A-2 
receive-end-of-group (RCVENDGRP) A-2 
receive-function management header 
(RCVFMH) A-2 
receive-negative-response (RCVNEGRSP) A-2 
receive-turnaround (RCVTRNRND) A-2 
RECID (record-identification) A-2 
record-identification (RECID) A-2 
request-to-write (RQSWRT) 4-11, A-2 
respond-to-confirm (RSPCONFIRM) 4-11, A-2 
RQSWRT (request-to-write) 4-11, A-2 
RSPCOMFIRM (respond-to-confirm) 4-11, A-2 
SECURITY (security) A-2 
summary table A-2 
TIMER (timer) 4-12, A-2 
variable-length data (VARLEN) A-2 
VARLEN (variable-length data) A-2 


language 


ILE C/400 1-1 

ILE COBOL/400_ 1-1 
ILE FORTRAN/400_ 1-1 
ILE RPG/400_ 1-1 


length restriction 


data 1-1 


library name 4-7 
line 


communications 
Ethernet 2-1 
IDLC (integrated services digital network data link 
control) 2-1 
SDLC (synchronous data link control) 2-1 
token-ring network 2-1 
X.25 2-1 
creating a description 2-1 
valid types for SNUF 2-1 


logical record 


description 5-2 
sending in batch mode 4-8 
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logical record (continued) 
sending in interactive mode 4-8 

logical unit (LU) 
defining C-2 
freed by the release operation 4-13 
parameters C-2 
starting, using program start request C-10 
VTAM creation C-2 

LU (logical unit) 
defining C-2 
freed by the release operation 4-13 
parameters C-2 
starting, using program start request C-10 
VTAM creation C-2 


M 
maximum file wait time (WAITFILE) parameter 4-2 
message 

arrangement (IMS/VS) 5-3 

format 5-3 

format services for IMS/VS_ 5-13 

headers 5-9 


output (IMS/VS) 5-13 
receiving from host system 5-3 
requesting for IMS/VS__ 5-11 
sending to SNUF 5-3 
valid return codes_ B-1 
message format services 5-13 
message protection (MSGPTC) parameter 4-4 
mode 
batch 5-2 
contention 5-4 
forced terminal response 5-12 
half-duplex flip-flop 5-1 
interactive 5-2 
negated terminal response 5-12 
MSGPTC (message protection) parameter 4-4 


N 


negative-response (NEGRSP) keyword 4-11 
NEGRSP (negative-response) keyword 4-11 
$$NRSP system-supplied format A-2 
$$NRSPNI system-supplied format A-2 


O 


operating in terminal response mode 5-11 
operation 

acquire 4-7 

Change Call (CHNG) C-10 

get-attributes 4-12 

input using a batch session 5-2 

input using an interactive session 5-2 

Insert Call (ISRT) C-10 


operation (continued) 
open 4-7 
read 4-9 
read-from-invited-program-devices 4-9 
write 4-8 
output message 5-13 
Override Intersystem Communications Function 
Program Device Entry (OVRICFDEVE) command 
completing an input operation 5-11 
defining a protected session 5-4 
description 4-2 
opening communications 5-5 
parameters 4-2 
passing message headers 5-9 


processing 
chains 5-2 
headers 5-13 
sending 


transactions 5-10 
user passwords 5-9 
sending the Ready-to-Receive command 5-11 
specifying 
application identifier for CICS/VS example C-6 
application identifier for IMS/VS example C-10 
application identifier for VTAM/NCP example C-3 
chains 5-2 
interactive session C-6 
record length C-6, C-10 
Override with Intersystem Communications Func- 


p 


padding requirements 5-7 

parameter 
ADDICFDEVE (Add Intersystem Communications 

Function Program Device Entry) command 4-2 

APPID (application identifier) 4-3 
application identifier (APPID) 4-3 
BATCH (batch activity) 4-4 
batch activity (BATCH) 4-4 
BLKLEN (block length) 4-5 
block length (BLKLEN) 4-5 
CMNTYPE (communications type) 4-3 
communications type (CMNTYPE) 4-3 
DEV (device) 4-3 
device (DEV) 4-3 
EMLDEV (emulation device) 4-5 
emulation device (EMLDEV) 4-5 
end session with host (ENDSSNHOST) 4-4 
ENDSSNHOST (end session with host) 4-4 
file (FILE) 4-2 
FMTSLT (format select) 4-3 
format select (FMTSLT) 4-3 
HDRPROC (header processing) 4-4 
header processing (HDRPROC) 4-4 
HOST (host type) 4-4 
host type (HOST) 4-4 
initialize self-selection (INZSELF) 4-4 
INZSELF (initialize self-selection) 4-4 
maximum file wait time (WAITFILE) 4-2 


tion File (OVRICFF) command 
description 4-1 
OVRICFDEVE (Override Intersystem Communica- 
tions Function Program Device Entry) command 


message protection (MSGPTC) 4-4 
MSGPTC (message protection) 4-4 
PGMDEV (program device) 4-3 


completing an input operation 5-11 
defining a protected session 5-4 
description 4-2 

opening communications 5-5 
parameters 4-2 

passing message headers 5-9 


processing 
chains 5-2 
headers 5-13 
sending 


transactions 5-10 
user passwords 5-9 
sending the Ready-to-Receive command 5-11 
specifying 
application identifier for CICS/VS example C-6 
application identifier for IMS/VS example C-10 
application identifier for VTAM/NCP example C-3 
chains 5-2 
interactive session C-6 
record length C-6, C-10 


program device (PGMDEV) 4-3 
RCDLEN (record length) 4-5 
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parameter 4-4 
special host application (GSPCHOSTAPP) 
parameter 4-4 
specifying 
APPID (application identifier) for IMS/VS_ C-10 
interactive session 
cancel function 4-10 
CICS/VS example C-6 
read operation 4-9 
starting 
batch mode 4-8 
logical units C-10 
programs using program start request 5-5 
protected sessions 5-4 
session 4-7 
transaction 4-7 
synchronous data link control (SDLC) line 
available for SNUF_ 1-1 
line description 2-1 
system 
See also CICS/VS (Customer Information Control 
System for Virtual Storage) system 
See also IMS/VS (Information Management System 
for Virtual Storage) system 
message 
receiving from host 5-3 
system-supplied formats A-2 
tasks 1-1 
system-supplied format 
$$CANL A-2 
$$CANLINV A-2 
$$CANLNI A-2 
$$EOS A-2 
$$EVOK A-2 
$$EVOKET A-2 
$$EVOKNI A-2 
$$FAIL A-2 
$$NRSP_ A-2 
$$NRSPNI A-2 
$$POSRSP A-2 
$$RCD A-2 
$$SEND A-2 
$$SENDE A-2 
$$SENDET A-2 
$$SENDFM A-2 
$$SENDNF A-2 
$$SENDNI A-2 
$$TIMER A-2 
system-supplied function 4-11 
system-supplied operation 4-11 
System/370 1-1 
System/390 1-1 
Systems Network Architecture (SNA) 
3270 program interface definition D-1 
BIND command D-14 


Systems Network Architecture (SNA) (continued) 
communicating with a host system 1-1 
functions available 1-1 
sense codes supported by SNUF 4-11 

Systems Network Architecture upline facility (SNUF) 
3270 support 1-1 
communications network example 1-2 
configuration 

capabilities 1-1 
checking for function-management-header 
validity 4-8 
communications lines available 1-1 
description 1-1 
installing support 2-1 
definition 1-1 
running communications 3-1 
sending messages to 5-3 
valid host system 1-1 


T 


terminal response mode (IMS/VS)_ 5-11 
timer function 

considerations 5-2 

description 4-12 

intervals 4-12 
TIMER keyword 4-12 
$$TIMER system-supplied format A-2 
timer-run-out return code 4-12 
token-ring network communications line 

available for SNUF 1-2 

line description 2-1 
transaction 

codes 4-7, 5-8 

data 4-7 

definition 4-7 

ending 4-12 

sending to IMS/VS 

example 5-10 

start record 4-7 

starting 4-7 

terminal response mode 5-12 

without waiting for output 5-10 


U 


unformatted program interface D-4 
user data 5-5 
user ID 4-7 
user password 
evoke function 4-7 
sending 5-9 
using 
remote program start request 5-5 


V 


Variable-length data (VARLEN) keyword 4-8 
VARLEN (Variable-length data) keyword 4-8 
Vary Configuration (VRYCFG) command 
description 3-1 
establishing communications 5-5 
sending a BIND command 5-6 
vary on and vary off support 3-1 
Virtual Telecommunications Access Method (VTAM) 
generation example C-3 
programming considerations 
“EXEX program start request 5-5 
*TXTC program start request 5-5 
“TXTX program start request 5-5 
defining logical unit C-2 
defining physical unit C-1 
example C-3 
PU definition parameters C-1 
sending the BIND command C-2 
VM/MVS Bridge 5-13 
VRYCFG (Vary Configuration) command 
description 3-1 
establishing communications 5-5 
sending a BIND command 5-6 
VTAM (Virtual Telecommunications Access Method) 
generation example C-3 
programming considerations 
*EXEX program start request 5-5 
*TXTC program start request 5-5 
“TXTX program start request 5-5 
defining logical unit C-2 
defining physical unit C-1 
example C-3 
PU definition parameters C-1 
sending the BIND command C-2 


W 


WAITFILE (maximum file wait time) parameter 4-2 
write operation 
description 4-8 
programming considerations 
CICS/VS_ C-6 
IMS/VS_ C-6 
sending IMS/VS commands 5-9 
starting 
batch mode 4-8 
interactive mode 4-8 
write-with-detach function C-6 
writing 
application programs 
using SNA 3270 program interface D-3 
SNUF application programs 4-1 


Index X=15 


X 


X.25 communications line 
available for SNUF_ 1-2 
line description 2-1 


X-16 SNA Upline Facility Programming V4R1 


Reader Comments—We'd Like to Hear from You! 


AS/400 Advanced Series 
SNA Upline Facility Programming 
Version 4 


Publication No. $C41-5446-00 


Overall, how would you rate this manual? 


i ; Very 
Very ae Dissatis- LY. 
Satisfied | Satisfied fied Be. 


Overall satisfaction 


How satisfied are you that the information in this manual is: 


Accurate 


Complete 
Easy to find 


Easy to understand 


Well organized 


Applicable to your tasks 


THANK YOU! 


Please tell us how we can improve this manual: 


May we contact you to discuss your responses? _ Yes __ No 
Phone: ( ) Fax: ( ) Internet: 


To return this form: 
¢ Mail it 
e Fax it 
United States and Canada: 800+937-3430 
Other countries: (+1)+507+253-5192 
¢ Hand it to your IBM representative. 


Note that IBM may use or distribute the responses to this form without obligation. 


Name Address 


Company or Organization 


Phone No. 


Reader Comments—We'd Like to Hear from You! : Cut or Fold 


SC41-5446-00 SEES | Along Line 
== =F =8 
Fold and Tape Please do not staple Fold and Tape 

NO POSTAGE 
NECESSARY 
IF MAILED IN THE 
UNITED STATES 
ae 

BUSINESS REPLY MAIL — 
SS —_ 

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK ee 
_=<—_—_—_______} 

POSTAGE WILL BE PAID BY ADDRESSEE Ee 
Pe 

ATTN DEPT 542 IDCLERK ————————————l 

IBM CORPORATION 

3605 HWY 52 N 

ROCHESTER MN 55901-9986 

DebadvedadadadeeUDvcceccUMDadeadadacdeadeeldealealsl 
ae FoldandTape = = ~~—~—*~iPleasedonotstaple = = = ~~ FoldandTape 
Cut or Fold 


SC41-5446-00 : Along Line 


Printed in the United States of America 
on recycled paper containing 10% 
recovered post-consumer fiber. 


i | | | | | | | 


Spine information: 


= AS/4.00 Advanced Series SNA Upline Facility Programming Version 4 


